> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List, tag, publish, and delete templates

> List sandbox templates and read the paginated response, assign or remove release tags, publish a template, and delete a template by ID from the SDK or CLI.

List the sandbox templates available to the team from the CLI or the SDK. The SDK returns each template's ID, aliases or names, resource sizing, visibility and build metadata.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## List templates

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
res = ppio.template.list(
    template_type="template_build",  # or "snapshot_template"
    page=1,
    limit=20,
)

print(f"total: {res.total}, pages: {res.total_pages}")
for t in res.items:
    print(t.template_id, t.aliases, t.cpu_count, t.memory_mb, t.public)
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const paginator = ppio.template.list({
  templateType: 'template_build', // or 'snapshot_template'
  page: 1,
  limit: 20,
})

const page = await paginator.nextPage()
console.log(`total: ${page.total}, pages: ${page.totalPages}`)
for (const t of page.templates) {
  console.log(t.templateId, t.aliases, t.cpuCount, t.memoryMB, t.public)
}
```

```bash CLI theme={null}
# Pretty table (default); alias: template ls
ppio template list

# JSON output
ppio template list --output json

# Scope to a team
ppio template list --team <team-id>
```

## Response

The response is paginated. The top-level fields are:

> [tab] Python
>
> **items** `array`
>
> The templates on this page.
>
> **Template fields**
>
> **template\_id** `string`
>
> Template ID.
>
> **aliases** `array`
>
> Template aliases.
>
> **names** `array`
>
> Template names.
>
> **cpu\_count** `number`
>
> vCPU count.
>
> **memory\_mb** `number`
>
> Memory in MiB.
>
> **disk\_size\_mb** `number`
>
> Disk size in MiB.
>
> **envd\_version** `string`
>
> Envd version.
>
> **public** `boolean`
>
> Whether the template is public.
>
> **build\_id** `string`
>
> Latest build ID.
>
> **build\_count** `number`
>
> Number of builds.
>
> **created\_at** `Date`
>
> Creation time.
>
> **updated\_at** `Date`
>
> Last update time.
>
> **last\_spawned\_at** `Date or null`
>
> Last time a sandbox was spawned.
>
> **created\_by** `object or null`
>
> Creator, with an `id` and an `email`.
>
> **total** `number`
>
> Total number of templates.
>
> **page** `number`
>
> Current page number.
>
> **limit** `number`
>
> Items per page.
>
> **total\_pages** `number`
>
> Total number of pages.

> [tab] Node.js
>
> **templates** `array`
>
> The templates on this page.
>
> **Template fields**
>
> **templateId** `string`
>
> Template ID.
>
> **aliases** `array`
>
> Template aliases.
>
> **cpuCount** `number`
>
> vCPU count.
>
> **memoryMB** `number`
>
> Memory in MiB.
>
> **diskSizeMB** `number`
>
> Disk size in MiB.
>
> **envdVersion** `string`
>
> Envd version.
>
> **public** `boolean`
>
> Whether the template is public.
>
> **buildId** `string`
>
> Latest build ID.
>
> **buildCount** `number`
>
> Number of builds.
>
> **createdAt** `Date`
>
> Creation time.
>
> **updatedAt** `Date`
>
> Last update time.
>
> **lastSpawnedAt** `Date or null`
>
> Last time a sandbox was spawned.
>
> **createdBy** `object or null`
>
> Creator, with an `id` and an `email`.
>
> **total** `number`
>
> Total number of templates.
>
> **page** `number`
>
> Current page number.
>
> **limit** `number`
>
> Items per page.
>
> **totalPages** `number`
>
> Total number of pages.

## Assign tags

Tags label template builds for release management without changing the underlying template name. Use `assign_tags` in Python or `assignTags` in Node.js to assign one or more tags to an existing template build.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()

ppio.template.assign_tags('my-template:v1.0', 'production')
ppio.template.assign_tags('my-template:v1.0', ['production', 'stable'])
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

await ppio.template.assignTags('my-template:v1.0', 'production')
await ppio.template.assignTags('my-template:v1.0', ['production', 'stable'])
```

## Remove tags

Use `remove_tags` in Python or `removeTags` in Node.js to remove one or more tags from a template by name.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()

ppio.template.remove_tags('my-template', 'production')
ppio.template.remove_tags('my-template', ['production', 'staging'])
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

await ppio.template.removeTags('my-template', 'production')
await ppio.template.removeTags('my-template', ['production', 'staging'])
```

> [!NOTE]
>
> `assign_tags` / `assignTags` returns tag information. `remove_tags` / `removeTags` returns nothing. Both accept a single tag string or a list of tags.

## Delete a template

A template can be deleted by ID from the CLI or the SDK. Deleting a template is permanent.

> [!WARNING]
>
> Deleting a template is irreversible. The CLI asks for confirmation by default; pass `-y` or `--yes` to skip it. The CLI also removes the local `ppio.toml` config for the deleted template.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()

deleted = ppio.template.delete('tpl_123')
print(deleted)  # True if deleted, False if not found
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const deleted = await ppio.template.delete('tpl_123')
console.log(deleted) // true if deleted, false if not found
```

```bash CLI theme={null}
# Delete by template ID (alias: template dl)
ppio template delete <template-id>

# Delete the template defined by ppio.toml, without confirmation
ppio template delete -y

# Pick from an interactive list
ppio template delete --select --team <team-id>
```

## Publish and unpublish

Publishing makes a template public to everyone outside the team. Unpublishing makes it private to the team again. Both commands set the template's `public` flag.

> [!WARNING]
>
> The command asks for confirmation before changing visibility, because publishing makes the template public to everyone outside the team. Pass `-y` or `--yes` to skip the prompt.

### Usage

```bash CLI theme={null}
# Publish (alias: tpl pb)
ppio template publish [template]

# Unpublish (alias: tpl upb)
ppio template unpublish [template]
```

### Arguments

Choose the templates to act on in one of three ways: pass `[template]`, omit it to use `ppio.toml`, or pass `--select`.

**\[template]** `string`

Optional. Acts on the template with the given template ID. When omitted, uses the template defined by `ppio.toml` in the root directory.

### Options

**-s, --select** `boolean`

Selects templates from an interactive list, which shows only the templates eligible for the action.

**-p, --path** `string`

Root directory where the command runs. Defaults to the current directory.

**--config** `string` (default: ./ppio.toml)

Path to the sandbox config toml.

**-t, --team** `string`

Team ID the operation is associated with, used with `--select`.

**-y, --yes** `boolean`

Skips the manual confirmation prompt.

### Examples

```bash By template ID theme={null}
ppio template publish <template-id>
```

```bash From ppio.toml theme={null}
ppio template publish -y
```

```bash Interactive theme={null}
ppio template unpublish --select --team <team-id>
```

On success, publishing prints the public names the template was published as:

```text Output theme={null}
- Publishing sandbox template <template>
  Published as: <name>
```


## Related topics

- [What is a sandbox template?](https://docs.ppio.ai/sandbox/templates/overview.md)
- [Build a template with the SDK](https://docs.ppio.ai/sandbox/templates/build.md)
- [Manage sandboxes in the PPIO console](https://docs.ppio.ai/sandbox/console.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.