Automate the CLI

Automation should validate Templates before live execution, authenticate from a secrets store, and treat Task creation as an explicit step.

name: Atomize

on:
  workflow_dispatch:

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

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

      - name: Validate templates
        run: atomize validate template:backend-api --strict --quiet

      - name: Configure profile
        env:
          AZURE_DEVOPS_PAT: ${{ secrets.AZURE_DEVOPS_PAT }}
        run: |
          echo "$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: Generate tasks
        run: |
          atomize generate template:backend-api \
            --execute \
            --auto-approve \
            --output report.json

Use --auto-approve only in jobs where Task creation is intentional. A job that should only check the plan can run the same command without --execute: dry runs never create Tasks.

Authentication

Create a short-lived Connection Profile in the job from your secrets store, and pass the token through --pat-stdin so it stays out of process listings and logs. See CI/CD Setup for the full options and Profile Resolution Order for how commands choose a profile.

Machine-readable output

Command	Output
generate --output <file>	Writes the run's JSON report to a file alongside the normal terminal output. Descriptions, custom field values, and raw platform data are left out unless you pass --include-sensitive-report-data.
generate --json	Prints the JSON report to stdout and nothing else. It runs a dry run unless you also pass --execute.
generate --json-stream	Prints newline-delimited JSON: a {"event":"progress",...} line per progress event, then a final {"event":"report",...} line.
validate --output json	Prints the validation result as JSON to stdout.
auth list --json, template list --json, fields list --json, queries list --json	Print results as JSON to stdout, with progress on stderr.

--json and --json-stream cannot be combined, and both imply --quiet.

Exit codes and failure handling

Code	generate	validate
0	Every Story succeeded, including a dry run	The Template is valid
1	One or more Stories failed, or the run was refused	Validation failed
2	No Stories matched the filter or --story IDs
3	Authentication failed

The exit codes are the same with --json and --json-stream. A run with no matching Stories exits 2 and still prints its report, with storiesProcessed: 0.

• By default generate stops after the first failing Story. --continue-on-error processes the rest and still exits 1 if any failed.
• Test against a few items with --limit <n> before a full --execute run.
• Re-run failed Stories with --story <ids...>. With excludeIfHasTasks: true in the Template, Stories that already received Tasks are skipped, so a retry does not duplicate them.

See the CLI Reference for every command and flag.