CLI Commands

The ado-aw CLI provides commands for authoring, compiling, and managing the full lifecycle of Azure DevOps agentic pipelines.

Global flags

These flags apply to all commands:

--verbose, -v — enable more detailed logging
--debug, -d — enable debug logging (implies verbose)
--log-output-dir <path> — write log files to a specific directory (overrides ADO_AW_LOG_DIR)

Authoring commands

`init`

Initialize a repository for AI-first agentic pipeline authoring. Creates .github/agents/ado-aw.agent.md, a Copilot dispatcher agent that routes to the create, update, and debug prompts.

ado-aw init [--path <path>] [--force] [--agency]

Options:

--path <path> — target directory (defaults to current directory)
--force — bypass the GitHub-remote guard (use when running inside a GitHub-hosted repository like githubnext/ado-aw)
--agency — additionally scaffold an Agency / Claude Code plugin under agency/plugins/ado-aw/ plus repo-root marketplace catalogs (.claude-plugin/marketplace.json and .github/plugin/marketplace.json); additive to the standard agent file. See the Agency Plugin reference.

`compile [<path>]`

Compile a markdown agent file into Azure DevOps pipeline YAML. If you omit the path, ado-aw auto-discovers and recompiles all agentic pipeline sources in the current directory.

ado-aw compile [<path>] [--output <path>]

Options:

--output, -o <path> — write the generated YAML to a specific file or directory; if an existing directory is given, the filename is derived from the source (e.g. agent.md → agent.lock.yml)
--force — bypass the GitHub-remote guard
--skip-integrity — (debug builds only) skip the “Verify pipeline integrity” step
--debug-pipeline — (debug builds only) include MCPG debug diagnostics in the generated pipeline

`check <pipeline>`

Verify that a compiled pipeline still matches its source markdown. Useful as a CI gate to catch un-regenerated pipelines.

ado-aw check <pipeline>

The source markdown path is auto-detected from the @ado-aw header inside the compiled YAML.

IR analysis commands

These commands work entirely offline against a local agent source file — no ADO connection required. They compile the source into the typed IR and then answer questions about it.

`inspect <source>`

Print a human summary (or full JSON) of the typed IR for an agent markdown source: stages, jobs, steps, output declarations, and derived dependsOn edges.

ado-aw inspect <source> [--json]

Options:

--json — emit the full PipelineSummary as JSON instead of the terse human summary

`graph dump <source>`

Dump the resolved dependency graph in text, JSON, or Graphviz DOT format.

ado-aw graph dump <source> [--format text|json|dot]

Options:

--format text|json|dot — output format (default: text)

`graph deps <source> <step>`

Traverse the dependency chain upstream or downstream from one named step.

ado-aw graph deps <source> <step> [--direction upstream|downstream] [--json]

Options:

--direction upstream|downstream — traversal direction (default: upstream)
--json — emit machine-readable JSON

`graph outputs <source>`

Print every declared step output and the steps that consume it.

ado-aw graph outputs <source> [--producer <step-id>] [--consumer <step-id>] [--json]

Options:

--producer <step-id> — filter to outputs declared by this step
--consumer <step-id> — filter to outputs consumed by this step
--json — emit machine-readable JSON

`whatif <source> --fail <id>`

Static reachability: given a step or job ID that is treated as failing, classify every downstream job as either skipped or runs_anyway based on their compiled ADO condition strings.

ado-aw whatif <source> --fail <step-or-job-id> [--json]

Options:

--fail <id> — (required) step or job ID to treat as failing
--json — emit a WhatIfReport as JSON

`lint <source>`

Run structural lint checks over an agent source file and print findings (errors, warnings, info). Exits with a non-zero code when any errors are found.

ado-aw lint <source> [--json]

Options:

--json — emit a LintReport as JSON

`catalog`

List the in-tree registries of safe-output tools, runtimes, first-class tools, engines, and models.

ado-aw catalog [--kind <category>] [--json]

Options:

--kind safe-outputs|runtimes|tools|engines|models — restrict output to one category; omit to see all
--json — emit the catalog as JSON

`trace <build-id-or-url>`

Trace a build’s failing-job chain by joining live audit data (downloaded from ADO) with the local typed-IR graph. Requires that the source markdown is available locally.

ado-aw trace <build-id-or-url> [--step <id>] [--json] [--org <url>] [--project <name>] [--pat <token>]

Options:

--step <id> — typed-IR step ID to focus the trace on
--json — emit a TraceReport as JSON
--org, --project, --pat — ADO context overrides (same as audit)

IDE / MCP integration

`mcp-author`

Run a local read-only MCP server over stdio for IDE and Copilot Chat integrations. Exposes all IR analysis tools — inspect_workflow, graph_dump, step_dependencies, step_outputs, whatif, lint_workflow, catalog, trace_failure, and audit_build — over the standard Model Context Protocol so your IDE agent can reason about workflows without manual CLI invocations.

ado-aw mcp-author

No flags; add the server to your IDE’s MCP config pointing to the ado-aw mcp-author command. See the Author MCP Server reference for tool parameters, IDE configuration snippets (VS Code, Claude Desktop, Cursor), and trust model.

Pipeline lifecycle commands

These commands interact with Azure DevOps build definitions and require ADO API access. They infer the ADO organization and project from the local git remote by default; pass --org and --project to override.

For ADO authentication, the commands try the Azure CLI (az login) first and fall back to prompting for a PAT. You can also set AZURE_DEVOPS_EXT_PAT in your environment to skip the prompt.

`secrets set <name> [<value>] [path]`

Set a pipeline variable (stored as isSecret=true) on every matched ADO definition.

ado-aw secrets set GITHUB_TOKEN [path]

Value resolution order: positional <value> argument → --value-stdin (one line from stdin) → interactive prompt with echo off.

Options:

--allow-override — set allowOverride=true; when omitted, allowOverride is preserved on existing variables and defaults to false for new ones
--value-stdin — read the value from a single line on stdin (mutually exclusive with the positional value)
--org <url> — Azure DevOps organization URL or bare org name
--project <name> — Azure DevOps project name
--pat <pat> — PAT for ADO API authentication
--definition-ids <ids> — explicit comma-separated definition IDs (skips auto-detection); mutually exclusive with --all-repos / --source
--all-repos — project-scope mode: search every ado-aw definition in the ADO project, not just those with a local lock file; mutually exclusive with --definition-ids
--source <path> — filter to definitions whose # ado-aw-metadata marker references this template path (e.g. agents/security-scan.md); activates the discovery code path; pairs with --all-repos to scope across the whole project
--include-disabled — include disabled / paused definitions in project-wide discovery (only effective with --all-repos or --source); by default disabled and paused definitions are skipped to speed up the Preview step
--dry-run — print the planned set without calling the ADO API

`secrets list [path]`

List variable names and their isSecret / allowOverride flags on every matched definition. Never prints values.

Options:

--json — emit machine-readable JSON
--org, --project, --pat, --definition-ids — same as secrets set
--all-repos, --source — same as secrets set
--include-disabled — same as secrets set

`secrets delete <name> [path]`

Delete a named variable from every matched definition. No-op when the variable is absent.

Options:

--org, --project, --pat, --definition-ids — same as secrets set
--all-repos, --source — same as secrets set
--include-disabled — same as secrets set
--dry-run — print the planned deletion without calling the ADO API

Project-scope discovery (`--all-repos` / `--source`)

By default, secrets commands match ADO definitions by scanning local lock files (the same auto-discovery used by compile and enable). Two opt-in flags activate Preview-driven discovery instead — useful when local checkouts of every consumer pipeline aren’t available:

--all-repos — search every ado-aw definition in the ADO project, including consumer pipelines that include ado-aw templates but live in other repos. No local checkout of those repos is required. This routes through ado-aw’s Preview API machinery, which calls ADO’s Pipeline Preview endpoint per definition and scans the expanded YAML for the ado-aw-marker step that every compiled pipeline now carries.
--source <path> — restrict results to definitions whose # ado-aw-metadata marker references the given template path. Useful for fan-out token rotation: ado-aw secrets set GITHUB_TOKEN --source agents/security-scan.md updates every pipeline that includes that template across the entire project. Without --all-repos, only definitions in the current repository are searched — pair with --all-repos to search the full project.

Both flags are mutually exclusive with --definition-ids. --definition-ids remains the explicit-ID escape hatch when you know exactly which definitions to target.

Disabled and paused definitions are pruned by default during project-wide discovery: the Preview step is expensive, so disabled / paused definitions are skipped before the expansion call to keep large projects fast. Definitions with no reported status are treated as active. Pass --include-disabled to include them — useful when you need to rotate a token on a pipeline that is temporarily paused.

# Rotate GITHUB_TOKEN on every ado-aw pipeline in the project
ado-aw secrets set GITHUB_TOKEN --all-repos

# Update only pipelines that include a specific template
ado-aw secrets set GITHUB_TOKEN --all-repos --source agents/security-scan.md

# Preview which definitions would be updated
ado-aw secrets set GITHUB_TOKEN --all-repos --dry-run

# Include disabled/paused pipelines in the sweep (e.g. to rotate their token before re-enabling)
ado-aw secrets set GITHUB_TOKEN --all-repos --include-disabled

`enable [path]`

Register an ADO build definition for each compiled pipeline discovered under path and ensure it is enabled. Matches existing definitions by YAML filename first, then by display name; creates a new definition when no match is found.

ado-aw enable [path] [options]

Options:

--org <url> — Azure DevOps organization URL or bare org name
--project <name> — Azure DevOps project name
--pat <pat> — PAT for ADO API authentication
--folder <ado-folder> — ADO folder for newly-created definitions (default: \); only applies on create
--default-branch <ref> — default branch for newly-created definitions (default: refs/heads/main)
--also-set-token — set GITHUB_TOKEN as a secret variable after creating new definitions
--token <value> — token value for --also-set-token (falls back to $GITHUB_TOKEN, then interactive prompt)
--dry-run — print the planned actions without calling the ADO API

`disable [path]`

Set queueStatus to disabled (or paused) on every matched ADO definition. Disabled definitions reject all queue requests; paused definitions queue scheduled runs but hold them without executing.

Options:

--paused — set queueStatus to paused instead of disabled
--org, --project, --pat — same as enable
--dry-run — preview the planned transitions without calling the ADO API

`remove [path]`

Destructive. Delete every matched ADO build definition. Bulk deletes (more than one match) require --yes; a single match on a tty prompts interactively.

Options:

--yes — required for bulk deletes (more than one match) and for any delete in a non-tty context
--org, --project, --pat — same as enable
--dry-run — preview the planned deletions without calling the ADO API

`list [path]`

List every matched ADO build definition along with its queueStatus, ADO folder, and latest-run summary.

Options:

--all — also include ADO definitions that do not match any local fixture
--json — emit machine-readable JSON
--org, --project, --pat — same as enable

`status [path]`

Show a denser per-pipeline status block for every matched definition: name, ID, folder, queueStatus, latest-run summary, and a deep link. --json emits the same shape as list --json.

Options:

--json — emit machine-readable JSON
--org, --project, --pat — same as enable

`run [path]`

Queue an ADO build for every matched definition. With --wait, polls each queued build to completion and exits with a non-zero code if any build failed.

ado-aw run [path] [--wait] [--parameters key=value]

Options:

--branch <ref> — source branch to queue (defaults to the definition’s defaultBranch)
--parameters <k=v> — ADO templateParameters as key=value pairs; repeatable and/or comma-separated. Values must not contain commas — use one --parameters flag per pair when values contain commas
--wait — poll each queued build to completion before exiting; aggregate result determines the exit code
--poll-interval <secs> — seconds between polls when --wait is set (default: 10)
--timeout <secs> — maximum seconds to wait when --wait is set (default: 1800)
--org, --project, --pat — same as enable
--dry-run — preview the planned queue body without calling the ADO API

`audit <build-id-or-url>`

Audit one completed Azure DevOps agentic pipeline build. Downloads the three audit artifact families (agent outputs, detection outputs, safe outputs), runs the built-in analyzers, and renders a structured console report.

ado-aw audit <build-id-or-url> [--json] [--output <dir>] [--artifacts <set,...>] [--no-cache]

Options:

--json — emit the full AuditData as JSON to stdout instead of the console report
-o, --output <dir> — local directory for downloaded artifacts and the cached report (default: ./logs; non-CLI entry points like ado-aw trace and the mcp-author tools default to ${TEMP}/ado-aw/audit instead)
--artifacts <set,...> — restrict download to agent, detection, and/or safe-outputs
--no-cache — re-process even when a cached run-summary.json already exists
--org, --project, --pat — same as enable

See the Audit reference for accepted URL formats, report shape, cache behavior, and permission failure handling.

Internal / pipeline runtime commands

These commands are used by the compiled pipeline itself and are not typically called by users directly.

`mcp <output_directory> <bounding_directory>`

Run SafeOutputs as a stdio MCP server (used by Stage 1). The <bounding_directory> guards against directory traversal attacks by ensuring the agent cannot influence folders outside this path.

ado-aw mcp <output_directory> <bounding_directory> [--enabled-tools <name>]

Options:

--enabled-tools <name> — only expose these safe output tools; repeat to allow more than one. If omitted, all tools are exposed

`mcp-http <output_directory> <bounding_directory>`

Run SafeOutputs as an HTTP MCP server (for MCPG integration). The <bounding_directory> guards against directory traversal attacks.

ado-aw mcp-http <output_directory> <bounding_directory> [options]

Options:

--port <port> — port to listen on (default: 8100)
--api-key <key> — API key for authentication (if not provided, one is generated)
--enabled-tools <name> — only expose these safe output tools; repeat to allow more than one. If omitted, all tools are exposed

`execute`

Execute safe outputs as the Stage 3 executor.

ado-aw execute [options]

Options:

--source, -s <path> — source markdown file (reads tool config from front matter)
--safe-output-dir <path> — directory containing safe output NDJSON (default: current directory)
--output-dir <path> — directory for processed artifacts (e.g., agent memory)
--ado-org-url <url> — Azure DevOps organization URL override
--ado-project <name> — Azure DevOps project name override
--dry-run — validate inputs without making write calls

Internal / build-time tools

These commands are hidden from --help and are intended for contributors working on the ado-aw compiler itself — not for end users or compiled pipelines.

`export-gate-schema`

Export the gate spec JSON Schema used by the scripts/ado-script TypeScript workspace for type code generation. Outputs JSON to stdout or to a file.

ado-aw export-gate-schema [--output <path>]

Options:

--output, -o <path> — write the schema to a file instead of stdout; parent directories are created automatically

Typical use (from the repo root):

cargo run -- export-gate-schema --output scripts/ado-script/schema/gate-spec.schema.json

See the ado-script reference for how this command fits into the TypeScript type-codegen workflow.

Deprecated commands

`configure` (deprecated alias)

ado-aw configure is a hidden alias for ado-aw secrets set GITHUB_TOKEN. It emits a deprecation warning and will be removed in a future release. Use ado-aw secrets set GITHUB_TOKEN instead.

Common examples

# Compile one source file
ado-aw compile agent.md

# Recompile all detected pipelines in the current directory
ado-aw compile

# Verify a generated pipeline
ado-aw check agent.lock.yml

# Inspect the typed IR for a source file (human summary)
ado-aw inspect agents/my-agent.md

# Inspect as machine-readable JSON (matches ado-aw audit pipeline_graph.summary)
ado-aw inspect agents/my-agent.md --json

# Dump the resolved dependency graph as Graphviz DOT
ado-aw graph dump agents/my-agent.md --format dot

# Trace which steps flow into a named step
ado-aw graph deps agents/my-agent.md my-step-id

# List all declared outputs and their consumers
ado-aw graph outputs agents/my-agent.md

# Simulate a failure: classify every downstream job as skipped or runs_anyway
ado-aw whatif agents/my-agent.md --fail agent_step_id

# Run structural lint checks
ado-aw lint agents/my-agent.md

# List all available safe-output tools
ado-aw catalog --kind safe-outputs

# Trace a failing build's job chain using ADO audit data + local IR
ado-aw trace 12345

# Set GITHUB_TOKEN on all matched pipelines (local lock files)
ado-aw secrets set GITHUB_TOKEN

# Set GITHUB_TOKEN on every ado-aw pipeline in the project (no local checkout needed)
ado-aw secrets set GITHUB_TOKEN --all-repos

# Register pipelines with ADO and set their token in one step
ado-aw enable --also-set-token

# Check which pipelines are registered and their latest status
ado-aw status

# Queue all matched pipelines and wait for them to finish
ado-aw run --wait

CLI Commands

Global flags

Authoring commands

init

compile [<path>]

check <pipeline>

IR analysis commands

inspect <source>

graph dump <source>

graph deps <source> <step>

graph outputs <source>

whatif <source> --fail <id>

lint <source>

catalog

trace <build-id-or-url>

IDE / MCP integration

mcp-author

Pipeline lifecycle commands

secrets set <name> [<value>] [path]

secrets list [path]

secrets delete <name> [path]

Project-scope discovery (--all-repos / --source)

enable [path]

disable [path]

remove [path]

list [path]

status [path]

run [path]

audit <build-id-or-url>

Internal / pipeline runtime commands

mcp <output_directory> <bounding_directory>

mcp-http <output_directory> <bounding_directory>

execute

Internal / build-time tools

export-gate-schema

Deprecated commands

configure (deprecated alias)

Common examples

`init`

`compile [<path>]`

`check <pipeline>`

`inspect <source>`

`graph dump <source>`

`graph deps <source> <step>`

`graph outputs <source>`

`whatif <source> --fail <id>`

`lint <source>`

`catalog`

`trace <build-id-or-url>`

`mcp-author`

`secrets set <name> [<value>] [path]`

`secrets list [path]`

`secrets delete <name> [path]`

Project-scope discovery (`--all-repos` / `--source`)

`enable [path]`

`disable [path]`

`remove [path]`

`list [path]`

`status [path]`

`run [path]`

`audit <build-id-or-url>`

`mcp <output_directory> <bounding_directory>`

`mcp-http <output_directory> <bounding_directory>`

`execute`

`export-gate-schema`

`configure` (deprecated alias)