Documentation

template commands

Development docs · main. Your installed version may differ.

template create

Create a new template or mixin using one of several methods.

Usage

atomize template create [options]
atomize tpl create [options]  # alias

Options

Option	Type	Description
`--type <type>`	string	Create a `template` or a `mixin` (prompted if omitted)
`--from <name>`	string	Start from an existing catalog template
`--scratch`	flag	Jump directly to the interactive wizard (skips mode selection)
`--ai`	flag	Use AI-assisted generation: describe the template in natural language
`--ground`	flag	Ground AI generation in your Azure DevOps project's work item types, states, fields and allowed values, saved queries, and area and iteration paths. Uses `--profile`, or the default profile
`--reference <path>`	string	With `--ai`, send a Reference Document: a Markdown or text file in the workspace, or `wiki:<wiki>/<page path>` for an Azure DevOps wiki page read through `--profile`. Repeatable
`--no-project-references`	flag	With `--ai`, leave out the Project Reference Documents saved in `.atomize/ai.yaml`
`--save-as <name>`	string	Name to save the template under in the catalog
`--scope <scope>`	string	Catalog to save to: `user` (`~/.atomize/catalog`) or `project` (`.atomize/catalog` in the project root). Default: `project` when the project root has its own `.atomize` folder, otherwise `user`.
`--open`	flag	Open the saved Atomize YAML file in a supported editor after successful creation
`--profile <name>`	string	Named ADO profile for `--ground` and field suggestions (uses default if omitted)
`-q, --quiet`	flag	Suppress non-essential output

Creation Modes

1. From Catalog Template

Start from a built-in or previously installed template.

atomize template create --from backend-api
atomize template create --from my-custom-template

Use atomize template list to see available names.

2. AI-Assisted Generation

Describe the template you need in plain language and let AI generate it.

# Basic AI generation
atomize template create --ai

# Ground the draft in your project's real types, fields, and saved queries
atomize template create --ai --ground --profile work-ado

# Also follow the process your team wrote down
atomize template create --ai --ground --reference docs/how-we-work.md --profile work-ado

Requires an active GitHub Copilot subscription. Atomize starts the bundled Copilot sign-in flow when needed.

3. Interactive Wizard (From Scratch)

Step-by-step guided builder for full control.

atomize template create --scratch

The wizard walks through basic information, filter configuration, task configuration (including composition: inheritance and mixins), estimation settings, validation rules, and metadata.

Creating Mixins

A mixin is a reusable group of tasks that can be mixed into multiple templates via the mixins: field. Use --type mixin to create one.

atomize template create --type mixin
atomize template create --type mixin --save-as security-review-tasks

See Template Reference: Composition for how to use mixins.

template improve

Asks Copilot to propose a revision of an existing Template and shows you the changes before anything is saved. Its options, review choices, and JSON report are described in Draft and improve with AI.

template list

List the Templates and Mixins in the Catalog, from built-in, personal, and project scope. Each item shows its ref, scope, and path, and any Catalog Override or Template Lineage.

Usage

atomize template list [options]
atomize template ls   # alias
atomize tpl ls        # alias

Options

Option	Description
`--type <type>`	Filter by type: `template` or `mixin`
`--json`	Print results as JSON to stdout; progress messages go to stderr

Output

  Templates

  backend-api
    Backend API (Contoso)
    Standard backend API development with database integration
    ref: template:backend-api  scope: your project
    path: ~/src/contoso-app/.atomize/catalog/templates/backend-api.atomize.yaml
    ⚠ overrides: built-in at <Atomize>/catalog/templates/backend-api.atomize.yaml (read-only)

  mobile-feature
    Mobile Feature
    Feature breakdown with device testing
    ref: template:mobile-feature  scope: your project
    path: ~/src/contoso-app/.atomize/catalog/templates/mobile-feature.atomize.yaml
    ↖ based on: built-in template:feature-development

  feature-development
    Feature Development
    Foundation for feature development templates. Extend this to inherit a standard task set and filter.
    ref: template:feature-development  scope: built-in
    path: <Atomize>/catalog/templates/feature-development.atomize.yaml (read-only)

  Mixins

  documentation
    Documentation Tasks
    Standard documentation tasks. Mix into any template to ensure docs are part of the definition of done.
    ref: mixin:documentation  scope: built-in
    path: <Atomize>/catalog/mixins/documentation.atomize.yaml (read-only)

template install

Install a template or mixin from a local file or HTTPS URL into the catalog.

Usage

atomize template install <source> [options]
atomize tpl install <source> [options]  # alias

Arguments

Argument	Description
`<source>`	Path to a local YAML file or an HTTPS URL

Options

Option	Description
`--type <type>`	Force type: `template` or `mixin` (auto-detected from file content if omitted)
`--overwrite`	Overwrite if a template with the same name already exists
`--scope <scope>`	Installation scope: `user` (`~/.atomize/catalog`) or `project` (`.atomize/catalog` in the project root: the nearest folder with a `.atomize` folder, otherwise the git repo root, otherwise the current directory). Without `--scope`, it's `project` when the project root has its own `.atomize` folder, meaning the team has opted in, and `user` otherwise.
`--open`	Open the installed Atomize YAML file in a supported editor after successful installation
`-q, --quiet`	Suppress non-essential output

Examples

# Install from a local file
atomize template install ./templates/my-api.yaml

# Install from a URL (shared team template)
atomize template install https://example.com/templates/security-review.yaml

# Install as project-scoped (stored in .atomize/ next to your code)
atomize template install ./templates/sprint-tasks.yaml --scope project

# Overwrite an existing template
atomize template install ./templates/backend-api.yaml --overwrite

Scopes:

user (shown as "personal"): installed to ~/.atomize/catalog/, available across all projects
project (shown as "your project"): installed to <workspace>/.atomize/catalog/, scoped to the discovered Workspace Root

Without --scope, project is used when the Workspace Root has its own .atomize folder, and user otherwise.

Editor handoff:

Pass --open to template create or template install to open the saved Atomize YAML file after success. ATOMIZE_EDITOR accepts supported editor identifiers only: code, cursor, or zed. Atomize appends the saved file path to its owned editor command and ignores arbitrary VISUAL and EDITOR command strings for this handoff. If no supported editor CLI is available, use the printed manual hint.

template remove

Remove a template or mixin from your personal Catalog. Built-in items cannot be removed, and project items are files in the repository: delete them through your team's review instead.

Usage

atomize template remove <name> [options]
atomize template rm <name> [options]   # alias

Arguments

Argument	Description
`<name>`	Template ref (`template:<name>` or `mixin:<name>`) or bare name

Options

Option	Description
`--type <type>`	Restrict to a specific type: `template` or `mixin`
`-f, --force`	Skip confirmation prompt

Examples

atomize template remove my-api-template
atomize template remove mixin:security-tasks
atomize template remove my-api-template --force

template resolve

Resolve a composed template (one that uses extends or mixins) and print the fully merged YAML. Useful for debugging composition and verifying the final template before use.

Usage

atomize template resolve <template> [options]

Arguments

Argument	Description
`<template>`	Template ref (`template:<name>`) or path to a YAML file

Options

Option	Description
`--validate`	Also run schema validation on the resolved template
`-q, --quiet`	Print only the resolved YAML, no decorative output

Examples

# Resolve and preview a composed template
atomize template resolve template:my-api

# Resolve from a file
atomize template resolve ./templates/composed.yaml

# Resolve, validate, and pipe to a file
atomize template resolve template:my-api --quiet > resolved.yaml

# Resolve and validate in one step
atomize template resolve template:my-api --validate

template metadata

Read Azure DevOps project metadata as a single JSON document: work item types, states, area paths, iteration paths, teams, saved queries, and task field schemas. Any user or script can call it directly for the same JSON, for example to build custom tooling around a project's Azure DevOps schema.

Usage

atomize template metadata [options]
atomize tpl metadata [options]  # alias

Options

Option	Description
`--profile <name>`	Named Azure DevOps connection profile (uses the default if omitted)
`--json`	Suppress non-JSON status output, for piping to another tool

The command always prints indented JSON to stdout, whether or not --json is passed; --json only silences surrounding log/status output, matching the convention used by fields list --json and queries list --json.

Output

A single JSON object:

{
  "workItemTypes": ["User Story", "Bug", "Task"],
  "statesByWorkItemType": {
    "User Story": ["New", "Active", "Resolved", "Closed"],
    "Bug": ["New", "Active", "Resolved", "Closed"]
  },
  "areaPaths": ["MyProject", "MyProject\\Backend"],
  "iterationPaths": ["MyProject\\Sprint 1", "MyProject\\Sprint 2"],
  "teams": ["Backend Team", "Frontend Team"],
  "savedQueries": [{ "id": "...", "path": "Shared Queries/Teams/Backend/Active Bugs" }],
  "taskFields": [],
  "fieldsByWorkItemType": {}
}

taskFields holds the field schema for the Task work item type; fieldsByWorkItemType holds field schemas keyed by every work item type returned in workItemTypes. Both use Azure DevOps's field-schema shape (reference name, type, allowed values).

Examples

atomize template metadata --profile work-ado

atomize template metadata --profile work-ado --json > project-metadata.json

Requires a Connection Profile (see Auth Guide): there is no offline mode, since the output is Azure DevOps project data.

template migrate

Move catalog items from the legacy .atomize/templates folder into the current .atomize/catalog folder.

Usage

atomize template migrate [options]

Options

Option	Description
`--scope <scope>`	`user` (default, `~/.atomize`), `project` (the current project's `.atomize`), or `all`
`--dry-run`	Report what would move without writing or deleting files
`--cleanup-dirs`	Remove the empty legacy folders after migration

Items whose names already exist in the current catalog are skipped and reported. Each migrated item is copied to the current catalog and its legacy file removed.

Examples

atomize template migrate --dry-run
atomize template migrate --scope all --cleanup-dirs