> ## 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.

# Tags & versioning

> Use tags, aliases, visibility, and deletion to manage template versions.

Build with a tag when callers should launch a stable versioned ref:

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  build = Template.build(builder, name="agent-template", tags=["stable"])
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  const template = await client.templates.builder()
    .fromPythonImage("3.12")
    .build({ name: "agent-template", tags: ["stable"] });
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template build --from-python-image 3.12 --name agent-template --tag stable
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # tags is part of the build request body. Builds stream over SSE.
  curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"name": "agent-template", "tags": ["stable"], "base_image": "python:3.12"}'
  ```
</CodeGroup>

Assign or remove tags after a template exists:

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  tags = Template.get_tags("agent-template")
  print(tags)

  Template.assign_tags("agent-template", ["stable", "prod"])
  Template.remove_tag("agent-template", "old")
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template tag list agent-template
  nullspace template tag assign agent-template stable prod
  nullspace template tag remove agent-template old
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # List tag -> build assignments
  curl "${NULLSPACE_API_URL}/v1/templates/agent-template/tags" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  # Assign or promote tags
  curl -X POST "${NULLSPACE_API_URL}/v1/templates/agent-template/tags" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"tags": ["stable", "prod"]}'

  # Remove a tag
  curl -X DELETE "${NULLSPACE_API_URL}/v1/templates/agent-template/tags/old" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

Manage aliases and visibility:

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Template.set_visibility("agent-template", "private")
  aliases = Template.list_aliases("agent-template")
  Template.remove_alias("agent-template", "old-alias")
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template visibility set agent-template private
  nullspace template alias list agent-template
  nullspace template alias remove agent-template old-alias
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # Set visibility (use /v1/templates/refs/{ref}/visibility for slash-bearing refs)
  curl -X PATCH "${NULLSPACE_API_URL}/v1/templates/agent-template/visibility" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"visibility": "private"}'

  # List aliases
  curl "${NULLSPACE_API_URL}/v1/templates/agent-template/aliases" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  # Remove an alias
  curl -X DELETE "${NULLSPACE_API_URL}/v1/templates/agent-template/aliases/old-alias" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

Delete template versions you no longer need:

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Template.delete("agent-template:old")
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  await client.templates.delete("agent-template:old");
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template delete agent-template:old
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X DELETE "${NULLSPACE_API_URL}/v1/templates/agent-template:old" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

<Note>
  The TypeScript SDK covers `list`, `get`, and `delete`; tag, alias, and
  visibility management are available in the Python SDK, CLI, or HTTP API.
</Note>

## Related

* [Names](./names)
* [Build](./build)