gh aw CLI Commands Reference

CLI vs MCP Tool — When to Use Each

- uses: github/gh-aw/actions/setup-cli@<version>
- run: gh aw compile

Command Reference

gh aw init

Initialize a repository for agentic workflows.

gh aw init

Creates .github/skills/agentic-workflows/SKILL.md and supporting files.

MCP equivalent: Not available — run from a local terminal or use the upgrade tool for updates.

gh aw compile

Compile workflow .md files into GitHub Actions .lock.yml files.

gh aw compile                     # Compile all workflows
gh aw compile <workflow-name>     # Compile a specific workflow
gh aw compile --strict            # Compile with strict mode validation
gh aw compile --validate          # Validate without emitting lock files
gh aw compile --fail-fast         # Stop at first error
gh aw compile --purge             # Remove orphaned .lock.yml files
gh aw compile --approve           # Approve new secrets / action changes

MCP equivalent: compile tool

Use the compile tool with workflow_name: "my-workflow"

gh aw run

Trigger a workflow on demand using workflow_dispatch.

gh aw run                           # Interactive mode — pick workflow and fill inputs
gh aw run <workflow-name>           # Run by short name
gh aw run <workflow-name>.md        # Alternative: explicit .md extension
gh aw run <workflow-name> --ref main              # Run on a specific branch/tag/SHA
gh aw run <workflow-name> --repeat 3              # Run 4 times total (1 + 3 repeats)
gh aw run <workflow-name> -F key=value            # Pass a specific input (alias: --raw-field)

MCP equivalent: Not available in the agentic-workflows MCP tool. If you cannot access the CLI, use the GitHub MCP server to dispatch the workflow:

Use the github MCP server tool "create_workflow_dispatch" with:
  - owner: <org>
  - repo: <repo>
  - workflow_id: <workflow-name>.lock.yml
  - ref: main
  - inputs: { ... }

gh aw logs

Download and analyze workflow execution logs.

gh aw logs                          # Logs for all agentic workflows
gh aw logs <workflow-name>          # Logs for a specific workflow
gh aw logs <workflow-name> --json   # JSON output for programmatic use
gh aw logs --engine copilot         # Filter by engine
gh aw logs -c 10                    # Last 10 runs
gh aw logs --start-date -1w         # Last week's runs
gh aw logs --start-date 2024-01-01 --end-date 2024-01-31
gh aw logs -o ./workflow-logs       # Save to directory
gh aw logs --repo owner/repo        # Query logs in another repository

MCP equivalent: logs tool

Use the logs tool with workflow_name: "my-workflow"

gh aw audit

Investigate a specific workflow run in detail (missing tools, safe outputs, metrics).

gh aw audit <run-id>                # Audit a single run
gh aw audit <run-id> --json         # JSON output
gh aw audit <base-id> <compare-id>  # Diff two runs (regression detection)
gh aw audit <id1> <id2> <id3> --json  # Multi-run diff

MCP equivalent: audit tool (single run) / audit-diff tool (multi-run comparison)

Use the audit tool with run_id: 20135841934

gh aw status

Show the status of all agentic workflows in the repository.

gh aw status
gh aw status --repo owner/repo    # Query status in another repository

MCP equivalent: status tool

gh aw checks

Show check run results for a workflow run.

gh aw checks <run-id>

MCP equivalent: checks tool

gh aw fix

Apply automatic codemods to fix deprecated fields in workflow files.

gh aw fix                   # Preview changes (dry run)
gh aw fix --write           # Apply changes

MCP equivalent: fix tool

gh aw upgrade

Upgrade the repository's agentic workflows configuration to the latest gh-aw version.

gh aw upgrade               # Upgrade agent files + codemods + compile
gh aw upgrade -v            # Verbose output
gh aw upgrade --no-fix      # Skip codemods and compilation

MCP equivalent: upgrade tool

gh aw add

Add a new shared workflow component as an import.

gh aw add <workflow-url>

MCP equivalent: add tool

gh aw update

Update imported shared workflow components.

gh aw update                                # Update all workflows from source
gh aw update <workflow-name>                # Update a specific workflow
gh aw update --major                        # Allow major version updates
gh aw update --create-pull-request          # Update and open a PR (alias: --pr)
gh aw update --repo owner/repo              # Update workflows in another repository (isolated shallow checkout)
gh aw update --cool-down 3d                 # Custom cooldown before applying pending releases

MCP equivalent: update tool

gh aw deploy

Deploy one or more workflows to a target repository by chaining update, add, compile --purge, and opening a pull request.

gh aw deploy <workflow>... --repo owner/repo            # Deploy listed workflows to target repo
gh aw deploy githubnext/agentics/ci-doctor --repo o/r   # Deploy a shared workflow
gh aw deploy ./local-workflow.md --repo owner/repo      # Deploy a local workflow
gh aw deploy <workflow> --repo owner/repo --force       # Overwrite existing files without confirmation

--repo is required. Useful for orchestrating remote rollouts across multiple repositories from a central deployer workflow.

MCP equivalent: Not available — run from a local terminal or invoke the CLI inside a workflow step with github/gh-aw/actions/setup-cli.

gh aw env

Manage compiler default variables (GH_AW_DEFAULT_*) in batch as GitHub Actions variables at repository, organization, or enterprise scope. The YAML file is flat and uses lowercase default_* keys (e.g. default_max_turns). Set a field to null to delete the variable; any non-null string sets it. Empty string "" is treated as set-to-empty, not delete.

gh aw env get [file]                          # Download defaults to file.yml (default name)
gh aw env get --scope org --org myorg         # Org-scope export
gh aw env update file.yml --scope repo        # Apply with interactive confirmation
gh aw env update file.yml --scope ent --enterprise myent --yes  # Skip confirmation
gh aw env update file.yml --scope repo --dry-run  # Preview without applying

Example file:

default_max_ai_credits: "1000"
default_detection_max_ai_credits: "400"
default_max_turns: "12"
default_model_copilot: "gpt-5-mini"
default_model_codex: null   # delete this variable

Recognized keys include default_max_ai_credits, default_detection_max_ai_credits, default_max_daily_ai_credits, default_timeout_minutes, default_max_turns, default_detection_model, default_utc, default_model_copilot, default_model_claude, default_model_codex. The compiler resolves model selection as GH_AW_MODEL_* → GH_AW_DEFAULT_MODEL_* → built-in engine fallback.

MCP equivalent: Not available — run from a local terminal.

gh aw mcp inspect

Inspect and analyze MCP server configurations in workflows.

gh aw mcp inspect <workflow-name>
gh aw mcp inspect <workflow-name> --inspector   # Launch web-based inspector UI
gh aw mcp list                                   # List workflows with MCP servers

MCP equivalent: mcp-inspect tool

MCP Tool ↔ CLI Quick Reference