Documentation

CLI reference

Development docs · main. Your installed version may differ.

Every Atomize CLI command and flag, from main. Each command group has its own page: auth, generate, preview and validate, template, and fields and queries. For task-focused guides, see Generate Tasks from the CLI and Automate the CLI.

Installation

# Global installation (recommended)
npm install -g @sppg2001/atomize

# Verify installation
atomize --version

# Show help
atomize --help

Aliases: Both atomize and atom work as the CLI command.

Global Options

These options work with any command:

Option	Description
`--version`	Print the installed version
`--help`	Show help for a command
`--env-file <path>`	Load environment variables from a file before running the command (shell environment takes precedence over file values)

Commands Overview

Command	Alias	Description
`auth`	-	Manage named connection profiles
`auth add`	-	Add a new connection profile
`auth list`	`auth ls`	List all saved profiles
`auth use`	-	Set a profile as the default
`auth remove`	`auth rm`	Remove a profile
`auth test`	-	Test connectivity for a profile
`auth rotate`	-	Replace the PAT for a profile
`generate`	`gen`	Generate tasks from user stories using a template
`preview`	-	Inspect template field requirements or simulate task generation against mock story data
`fields`	-	Browse Azure DevOps work item fields
`fields list`	`fields ls`	List available fields for the current project or work item type
`validate`	-	Validate a template file
`template`	`tpl`	Template management commands
`template create`	-	Create a new template interactively or with AI
`template improve`	-	Propose an AI improvement to an existing template and review it before saving
`template list`	`template ls`	List available templates and mixins from the catalog
`template install`	-	Install a template or mixin from a local file or HTTPS URL
`template remove`	`template rm`	Remove a user-installed template or mixin
`template resolve`	-	Resolve a composed template and print the merged result
`template metadata`	-	Read Azure DevOps project metadata as JSON, for visual template authoring surfaces
`template migrate`	-	Move catalog items from the legacy storage folder to the current catalog
`queries`	-	Browse Azure DevOps saved queries
`queries list`	`queries ls`	List saved queries with paths and IDs

Configuration

Connection Profiles

Credentials are managed as named Azure DevOps profiles, with one independent default.

atomize auth add work-ado
atomize auth use work-ado   # set as default profile
atomize auth test work-ado

AI-assisted template drafting (template create --ai) talks to Copilot without a Connection Profile: see Auth Guide - AI Drafting: Copilot Session. Only --ground uses a Connection Profile, to read your project's metadata; the profile's token is never sent to Copilot.

Environment Variables

Authentication:

export ATOMIZE_PAT="your-personal-access-token"          # Used by auth add

Profile selection:

export ATOMIZE_PROFILE="work-ado"       # Azure DevOps profile

Profile resolution order for ADO commands (generate, fields list, queries list, validate --profile, template metadata):

--profile <name> flag
ATOMIZE_PROFILE environment variable
Default profile (set via atomize auth use)

Logging:

export LOG_LEVEL="info"   # debug, info, warn, error

.env File

No .env file is loaded automatically. Use the global --env-file flag to load one explicitly:

atomize --env-file .env.work generate template:backend-api
atomize --env-file /etc/atomize/ci.env generate template:backend-api --execute --auto-approve

Shell environment variables always take precedence over values in the file.

Example .env file:

ATOMIZE_PROFILE=work-ado

Key	Action
`↑` / `↓`	Navigate between options in a list
`Enter`	Confirm selection or submit input
`Space`	Toggle selection (in multi-select prompts)
`Ctrl+C`	Cancel the current operation and exit

Examples

Complete Workflow: Azure DevOps

# 1. Save your Azure DevOps credentials
atomize auth add work-ado
atomize auth use work-ado

# 2. Verify the connection
atomize auth test work-ado

# 3. Browse available templates
atomize template list

# 4. Start from a catalog template
atomize template create --from backend-api --save-as my-backend

# 5. Validate it
atomize validate my-backend.yaml

# 6. Preview (dry run)
atomize generate my-backend.yaml

# 7. Execute
atomize generate my-backend.yaml --execute

AI-Assisted Template Creation

# 1. Describe your template to the AI (signs in to GitHub Copilot when needed)
atomize template create --ai

# 2. Optionally ground it in your project's real types, fields, and saved queries
atomize template create --ai --ground --profile work-ado

Using Composed Templates

# Install a shared mixin from a URL
atomize template install https://example.com/mixins/security-review.yaml

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

# Validate a composed template
atomize template resolve template:my-api --validate

Target Specific Stories

# Run only against specific story IDs (bypasses filter)
atomize generate template:backend-api --story STORY-101 STORY-102 STORY-103

CI/CD Integration

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Atomize
        run: npm install -g @sppg2001/atomize

      - name: Save connection profile
        run: |
          echo "${{ secrets.AZURE_DEVOPS_PAT }}" | atomize auth add ci \
            --org-url "${{ secrets.AZURE_DEVOPS_ORG_URL }}" \
            --project "${{ secrets.AZURE_DEVOPS_PROJECT }}" \
            --team "${{ secrets.AZURE_DEVOPS_TEAM }}" \
            --default \
            --pat-stdin \
            --insecure-storage

      - name: Validate Templates
        run: |
          for template in templates/*.yaml; do
            atomize validate "$template" --strict --quiet
          done

      - name: Generate Tasks
        run: |
          atomize generate template:backend-api \
            --execute \
            --auto-approve \
            --output task-report.json \
            --continue-on-error

Troubleshooting

"Not authenticated" error

atomize auth list
atomize auth add work-ado
atomize auth test work-ado
atomize auth use work-ado

"Template validation failed"

atomize validate template:my-template --strict

"No matching stories found"

# Test with mock platform first
atomize generate templates/my-template.yaml --platform mock

AI template generation fails

AI drafts and improvements authenticate through GitHub Copilot, not a Connection Profile: see Auth Guide - AI Drafting: Copilot Session.

"GitHub Copilot is not signed in": an interactive run starts sign-in for you. A non-interactive run can't, so run gh auth login in a terminal on that machine, then retry.
Project metadata or a wiki page can't be loaded: check the Connection Profile with atomize auth test. An interactive run lets you retry, continue without grounding, or cancel. Reading wiki pages needs the optional Wiki (Read) scope; rotate the token with atomize auth rotate to add it.
A Reference Document is refused: it must be a .md or .txt file inside the workspace. A document you named with --reference that can't be read stops the run.
The draft or proposal is still invalid after three attempts: in an interactive run, a draft can continue in the wizard, and an improvement can be retried or saved as a draft file beside the source. See template improve.

# Sign in to Copilot on this machine, then retry
gh auth login
atomize template create --ai

Enable debug logging

export LOG_LEVEL="debug"
atomize generate template:backend-api --verbose