> ## Documentation Index > Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt > Use this file to discover all available pages before exploring further. # Manage Templates > Build, inspect, tag, rename, and delete machine templates from the CLI. Use `nullspace template ...` when you want to create reusable machine environments without writing Python builder code. The CLI mirrors the SDK builder: choose one base image, add build steps, set runtime defaults, then publish a named template. ## Inspect Templates ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template list nullspace template list --fields id,canonical_ref,visibility nullspace template get team/agent-template:stable nullspace template get team/agent-template:stable --fields id,canonical_ref,visibility nullspace template exists team/agent-template:stable ``` `--fields` returns compact metadata for scripts and dashboards. Build commands take a single-segment `--name`; use `--tag` for version tags and template refs such as `team/agent-template:stable` for lookup and management. ## Build From An Image ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template build \ --from-python-image 3.12 \ --name fastapi-agent \ --tag stable \ --apt-install git,curl,rg \ --pip-install fastapi,uvicorn \ --copy-src ./app.py \ --copy-dst /workspace/app.py \ --set-workdir /workspace \ --start-cmd "uvicorn app:app --host 0.0.0.0 --port 8080" \ --ready-port 8080 ``` Base selectors include: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template build --from-ubuntu-image 22.04 --name ubuntu-tools nullspace template build --from-debian-image bookworm --name debian-tools nullspace template build --from-python-image 3.12 --name python-tools nullspace template build --from-node-image 20 --name node-tools nullspace template build --from-bun-image 1.2 --name bun-tools nullspace template build --from-image registry.example.com/team/app:1.0 --name app nullspace template build --from-template base --name base-plus-tools ``` Package install helpers accept comma-separated package lists. Add `--npm-global` immediately after `--npm-install`, `--bun-global` immediately after `--bun-install`, or `--pip-user-install` immediately after `--pip-install` to change install scope. ## Dockerfiles And Local Context ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template build \ --from-dockerfile ./Dockerfile \ --name dockerfile-template \ --file-context . \ --file-ignore node_modules \ --file-ignore .git ``` Inline Dockerfile content is also supported: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template build \ --from-dockerfile-content @Dockerfile.generated \ --dockerfile-path-hint Dockerfile \ --name generated-template ``` Unsupported Dockerfile instructions are emitted as structured warning log entries. Use render commands to inspect the generated request before building: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template render json --from-python-image 3.12 --name demo --apt-install git nullspace template render dockerfile --from-python-image 3.12 --name demo --apt-install git ``` ## Build Resources, Cache, And Logs ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template build \ --from-python-image 3.12 \ --name python-large \ --cpu-count 4 \ --memory-mb 2048 \ --skip-cache \ --log-format text ``` Start a background build when CI should poll later: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template build --from-python-image 3.12 --name python-next --tag next --background nullspace template builds python-next nullspace template build-status tb_123 --offset 0 nullspace template logs tb_123 nullspace template logs tb_123 --offset 10 --follow nullspace template cancel tb_123 --reason superseded nullspace template retry tb_123 --tag next nullspace template promote tb_123 --tag stable nullspace template wait tb_123 --poll-interval-ms 500 --log-format jsonl ``` Save `next_offset` from `build-status` output and pass it back as `--offset` to fetch only new build log entries. `template logs --follow` uses the canonical reconnectable log stream and keeps reading live entries until the build stream closes. `template cancel` is idempotent for terminal builds and records a durable cancelled log entry. `template retry` starts a new attempt from the sanitized persisted definition; supply any private base image credentials again through the SDK/API when the original build required them. `template promote` moves a tag to a retained ready build artifact. Use `template validate` and `template plan` to check the server-side request normalization without starting an executor: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template validate --from-python-image 3.12 --apt-install git nullspace template plan --from-python-image 3.12 --apt-install git --cpu-count 2 --memory-mb 1024 ``` ## Files, Repos, And Build Steps ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template build \ --from-ubuntu-image 22.04 \ --name tools \ --git-clone https://github.com/acme/repo.git \ --git-path /workspace/repo \ --git-branch main \ --run-cmd "python3 -m compileall /workspace/repo" \ --make-dir /workspace/logs \ --make-dir-mode 0755 \ --make-symlink-target /workspace/repo/bin/tool \ --make-symlink-path /usr/local/bin/tool ``` Use `--copy-items @copy.json` for many copy operations, or combine `--copy-src` and `--copy-dst` for one copy step. `--remove`, `--rename-src`, and related flags are available for cleanup and final filesystem shaping. ## Names, Tags, Aliases, And Visibility ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template reserve team/agent-template nullspace template namespace get team nullspace template rename team/agent-template agent-template-renamed nullspace template tag assign team/agent-template stable prod nullspace template tag list team/agent-template nullspace template tag remove team/agent-template old nullspace template alias list team/agent-template nullspace template alias remove team/agent-template old-alias nullspace template visibility set team/agent-template private nullspace template delete team/agent-template:old ``` `template rename` takes a template ref and a new name, not a full destination ref. Existing aliases are preserved by the API. ## Use A Template ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace machine create --template team/agent-template:stable ``` ## Manage Template Warm Pools Template warm pools keep ready capacity for a template: ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} nullspace template warm-pool create team/agent-template:stable \ --name agent-template-small \ --min-ready 2 \ --max-ready 4 \ --json nullspace template warm-pool wait twp_agent_template_small --min-ready 2 --json nullspace machine create --template team/agent-template:stable --warm-pool twp_agent_template_small --warm-pool-mode prefer --json nullspace template warm-pool drain twp_agent_template_small --json ``` Use `nullspace template warm-pool list`, `get`, `scale`, `enable`, `disable`, `reconcile`, and `delete` to operate pools. See [Template Warm Pools](../templates/warm-pools) for checkout modes and troubleshooting. ## Related * [Templates](../templates/overview) * [Build And Logs](../templates/build-logs) * [Tags, Names, And Visibility](../templates/tags-names) * [Template Warm Pools](../templates/warm-pools) * [CLI Reference](../reference/cli)