// Tools

xeroctl templates

Author, version, and apply chat templates that seed new workspace chats with a system prompt, tool allowlist, and approval policy. Companion to xeroctl chat new: define here, apply there.

// keys j / k step through sections. g then t jumps to the top.

Subcommands

Nine verbs. Click a row to jump to its full reference below.

listEnumerate templates by scope.
showPrint one template at active or pinned version.
createInsert a new template from a JSON file.
updateBump a template; server writes a new immutable version row.
deleteSoft-delete a template; --force skips the prompt.
promoteLift a project-scope template to platform scope.
versionsList immutable version history, newest first.
applySeed a workspace chat from a template; chat pins the version.
apply-from-dirGit-style sync of a directory of *.json files.

Overview

The templates command group manages chat templates that seed new chats with a system prompt, an optional tool allowlist, and an optional approval policy. Templates have platform, project, and workspace scope layers; project-scope templates can be promoted to platform scope. Every edit creates a new immutable version row; chats applied from a template pin the version they were applied at.

All chat-templates routes mount under /v1/ and require an api-key with the inference scope. Write operations (create, update, delete, promote) additionally require the management scope on the same api-key. Requests hit /v1/chat-templates/* and /v1/workspaces/:wid/chat-templates/* on the router.

For the end-to-end authoring workflow, see the XEM chat template authoring guide.

Usage Pattern

bash

                    xeroctl templates list [--workspace <wid>] [--scope all|platform|project|workspace]
xeroctl templates show <id-or-name> [--version <n>] [--workspace <wid>]
xeroctl templates create --file <path> [--workspace <wid>]
xeroctl templates update <id-or-name> --file <path> [--workspace <wid>]
xeroctl templates delete <id-or-name> [--force] [--workspace <wid>]
xeroctl templates promote <id-or-name> --scope platform
xeroctl templates versions <id-or-name> [--workspace <wid>]
xeroctl templates apply <id-or-name> --workspace <wid>
xeroctl templates apply-from-dir <dir> [--workspace <wid>]
                

File Payload

The create, update, and apply-from-dir subcommands consume a JSON payload. A minimal example (saved as drain-node.json):

json

                    {
  "name": "drain-kubernetes-node",
  "scope": "project",
  "description": "Safely drain a Kubernetes node for maintenance.",
  "system_prompt": "You are a Kubernetes operator. When asked to drain a node, cordon it first, drain with grace-period 60, verify no stuck pods, and stop.",
  "allowed_tools": ["kubectl_get", "kubectl_describe", "kubectl_cordon", "kubectl_drain"],
  "approval_policy": "elevated",
  "applicable_workspace_types": ["kubernetes"],
  "parameters_schema": {
    "type": "object",
    "properties": {
      "node_name": {"type": "string", "description": "Target node hostname"}
    },
    "required": ["node_name"]
  },
  "metadata": {
    "tags": "kubernetes,operations"
  }
}
                

Supported Fields

name (required): kebab-case identifier.
system_prompt (required): seed prompt for chats applied from this template.
description (optional): human-readable summary; surfaced by show.
allowed_tools (optional): list of tool names to allow; omit for unrestricted.
approval_policy (optional): one of standard, elevated, restricted.
applicable_workspace_types (optional): list of workspace types this template targets.
parameters_schema (optional): JSON Schema object describing parameters callers may pass when applying the template.
metadata (optional): free-form key/value object.
scope (optional, informational only): see note below.

Validation

name must be kebab-case (^[a-z0-9]([a-z0-9-]*[a-z0-9])?$).
system_prompt must be non-empty after trimming.
approval_policy, when present, must be one of standard, elevated, restricted.

The scope field in the file is informational only -- the route picks scope (project vs workspace) from the --workspace flag. The CLI surfaces a note when the file's scope does not match.

list

Lists chat templates. Without flags returns the project-scoped list (which already merges platform-scope templates).

bash

                    xeroctl templates list
xeroctl templates list --scope platform
xeroctl templates list --workspace ws_01HXXXX
                

Options

Option	Required	Description
`--workspace <wid>`	No	Filter by workspace external ID.
`--scope <s>`	No	One of `all` (default), `platform`, `project`, `workspace`.

Output columns: ID, Name, Scope, Version, Tools, Approval, Updated.

show

Shows the active version of a template. Pass --version <n> to inspect the immutable history at a specific version.

bash

                    xeroctl templates show drain-kubernetes-node
xeroctl templates show ctpl_01HXXXX --version 3
                

Arguments

Argument	Description
`id-or-name` (positional)	Template external ID (`ctpl_...`) or kebab-case name.

Options

Option	Required	Description
`--version <n>`	No	Pin output to a specific immutable version row.
`--workspace <wid>`	No	Workspace external ID used for client-side name resolution when `id-or-name` is a name rather than a `ctpl_` ID.

create

Creates a new chat template from a JSON file. Use --workspace to create at workspace scope; otherwise the template is created at project scope.

bash

                    xeroctl templates create --file drain-node.json
xeroctl templates create --file drain-node.json --workspace ws_kube_prod
                

Options

Option	Required	Description
`--file <path>`	Yes	Path to a JSON file describing the template (see File Payload).
`--workspace <wid>`	No	Optional workspace external ID. When set, the template is created at workspace scope.

Output (table mode):

text

                    template drain-kubernetes-node created
version: 1
scope: project
id: ctpl_01HXXXX
                

update

Patches an existing template from a JSON file. The server inserts a new version row and re-points the active pointer; the template ID stays stable.

bash

xeroctl templates update drain-kubernetes-node --file drain-node.json

Arguments

Argument	Description
`id-or-name` (positional)	Template external ID or name.

Options

Option	Required	Description
`--file <path>`	Yes	Path to a JSON file describing the template.
`--workspace <wid>`	No	Workspace external ID used for client-side name resolution when `id-or-name` is a name.

delete

Soft-deletes a template. Prompts for confirmation unless --force is passed.

bash

                    xeroctl templates delete drain-kubernetes-node
xeroctl templates delete ctpl_01HXXXX --force
                

Flags

Flag	Description
`--force`	Skip the confirmation prompt.
`--workspace <wid>`	Workspace external ID used for client-side name resolution when `id-or-name` is a name.

promote

Promotes a project-scoped template to platform scope. Demotion is not supported. The --scope flag is required and must equal platform; the CLI rejects other values client-side.

bash

xeroctl templates promote drain-kubernetes-node --scope platform

Options

Option	Required	Description
`--scope platform`	Yes	Target scope; must be `platform`.

versions

Lists the immutable version history of a template, newest first.

bash

xeroctl templates versions drain-kubernetes-node

Arguments

Argument	Description
`id-or-name` (positional)	Template external ID (`ctpl_...`) or kebab-case name.

Options

Option	Required	Description
`--workspace <wid>`	No	Workspace external ID used for client-side name resolution when `id-or-name` is a name.

Output columns: Version, Created, Created By, Tools, Approval.

To inspect a single version's payload, use templates show <id-or-name> --version <n>.

apply

Applies a template to a workspace. Seeds a new chat in the workspace with the template's system prompt, tool allowlist, and approval policy. The chat pins the template's current version snapshot.

bash

xeroctl templates apply drain-kubernetes-node --workspace ws_kube_prod

Options

Option	Required	Description
`--workspace <wid>`	Yes	Target workspace external ID.

Output:

text

                    template applied
chat_id: chat_01HXXXX
url: /chats/chat_01HXXXX
version_pinned: 3
                

For an apply-then-message round trip, see xeroctl chat new.

apply-from-dir

Syncs a directory of *.json template files in git-style mode. For each file:

Parse and validate locally. Hard-fail on parse errors.
Look up the template by name.
Absent: POST create.
Present, payload differs: PATCH (server bumps version).
Present, payload matches: skip (no-op).

Non-JSON files in the directory are ignored.

Known limitation: when --workspace is set, apply-from-dir issues POST against the workspace-scoped route (/v1/workspaces/:wid/chat-templates) for new templates, but PATCH updates always target the project-scoped route (/v1/chat-templates/{id}) regardless of the flag. The server still resolves the template by ID, but no workspace prefix is sent on the update path. Pass explicit ctpl_ IDs and verify the resulting scope after a sync if this matters for your workflow.

bash

                    xeroctl templates apply-from-dir ./templates
xeroctl templates apply-from-dir ./templates --workspace ws_kube_prod
                

Output

A transcript table (Name, Action, Version) followed by a one-line summary:

text

3 created, 7 updated, 12 unchanged

Examples

Create from a file and apply to a workspace

bash

                    xeroctl templates create --file drain-node.json
xeroctl templates apply drain-kubernetes-node --workspace ws_kube_prod
                

Promote to platform after iterating

bash

                    xeroctl templates update drain-kubernetes-node --file drain-node.json
xeroctl templates versions drain-kubernetes-node
xeroctl templates promote drain-kubernetes-node --scope platform
                

List as JSON

bash

xeroctl templates list --output json

xeroctl CLI

Back to the main xeroctl reference.

Authoring Guide

End-to-end walkthrough for authoring a chat template.