CLI & Tooling

🚀 Quick Start

Get up and running in three commands.

# 1. Install the GitHub CLI (if you don't have it)
#    → https://cli.github.com/

# 2. Install the gh-aw extension
$ gh extension install github/gh-aw

# 3. Initialize your repository
$ gh aw init

# That's it! Now create your first workflow:
$ gh aw new my-first-workflow --engine copilot
$ gh aw compile my-first-workflow
$ gh aw run my-first-workflow --push

📦 Installation Methods

Four ways to install, depending on your environment.

$ gh extension install github/gh-aw
$ gh aw version

$ gh extension install github/gh-aw@v0.57.0

# Upgrade a pinned version
$ gh extension remove gh-aw
$ gh extension install github/gh-aw@v0.58.0

# Latest version
$ curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

# Pinned version
$ curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s v0.57.0

# In your workflow YAML:
- name: Install gh-aw CLI
uses: github/gh-aw/actions/setup-cli@main
with:
  version: v0.57.0

📖 Command Reference

Complete reference for every gh aw command with syntax, options, and examples.

⚡ Core Commands

gh aw init

Initialize a repository for agentic workflows

What it creates: .gitattributes (marks .lock.yml as generated), .github/agents/agentic-workflows.agent.md (dispatcher agent), .gitignore entries, and MCP server config.

Options:

Examples:

$ gh aw init                              # Interactive mode
$ gh aw init --no-mcp                     # Skip MCP server
$ gh aw init --codespaces repo1,repo2     # Configure devcontainer for repos
$ gh aw init --create-pull-request         # Initialize via PR

gh aw compile

Compile Markdown to GitHub Actions YAML (.lock.yml) Core

The heart of gh-aw. Transforms .md workflow files into security-hardened .lock.yml files with schema validation, action SHA pinning, and guardrail configuration.

Options:

Examples:

$ gh aw compile                              # Compile all workflows
$ gh aw compile my-workflow                  # Compile a specific workflow
$ gh aw compile --watch                      # Auto-recompile on changes
$ gh aw compile --validate --strict          # Schema + strict security
$ gh aw compile --strict --zizmor            # Security scan (fail on findings)
$ gh aw compile --dependabot --purge         # Dependabot + cleanup

gh aw validate

Validate workflows with all linters enabled (no output generated)

Runs the compiler with all linters always-on — zizmor, actionlint, poutine — plus --validate and --no-emit. The go-to command for CI/CD gates.

Options:

Examples:

$ gh aw validate                              # Validate all workflows
$ gh aw validate my-workflow                  # Validate specific workflow
$ gh aw validate --strict --fail-fast         # Strict + stop on first error
$ gh aw validate --json                       # JSON output for CI

gh aw run

Trigger workflow execution in GitHub Actions

Options:

Examples:

$ gh aw run workflow                          # Run a workflow
$ gh aw run workflow --push                  # Compile → push → dispatch
$ gh aw run workflow --repeat 3              # Run 3 times
$ gh aw run workflow --dry-run               # Preview only
$ gh aw run w1 w2 --push --ref main         # Run multiple, push to main

gh aw list

List workflows (fast, no API queries)

Options:

Examples:

$ gh aw list                                  # List all workflows
$ gh aw list ci-                               # Filter by pattern
$ gh aw list --label automation --json          # Filter + JSON

gh aw status

Detailed workflow status with run info

Options:

Examples:

$ gh aw status                                # All workflows
$ gh aw status --ref main                      # Include latest run for main
$ gh aw status --repo owner/other-repo         # Different repo

gh aw version

Show CLI version

$ gh aw version
gh-aw v0.57.0 (2026-03-15)

🔄 Workflow Lifecycle

gh aw add

Add workflows from The Agentics collection or any repository

Options:

Examples:

$ gh aw add githubnext/agentics/ci-doctor           # Add from Agentics
$ gh aw add "githubnext/agentics/ci-*"              # Wildcard match
$ gh aw add ci-doctor --dir shared --force         # Into subdirectory
$ gh aw add ci-doctor --create-pull-request        # Add via PR

gh aw add-wizard

Interactive guided setup for adding workflows

Walks through engine selection, configuration, and compilation interactively.

$ gh aw add-wizard

gh aw new

Create a new workflow template

Options:

Examples:

$ gh aw new                              # Interactive mode
$ gh aw new my-workflow                   # Create named template
$ gh aw new my-workflow --engine claude   # With engine preset

gh aw fix

Auto-fix deprecated fields (dry-run by default)

Options:

Examples:

$ gh aw fix                              # Check all (dry-run)
$ gh aw fix --write                       # Apply fixes
$ gh aw fix my-workflow --write          # Fix specific workflow
$ gh aw fix --list-codemods               # Show available codemods

gh aw update

Update workflows from upstream (3-way merge by default)

Options:

Examples:

$ gh aw update                              # Update all sourced workflows
$ gh aw update ci-doctor                    # Update specific (3-way merge)
$ gh aw update ci-doctor --no-merge         # Force upstream version
$ gh aw update --create-pull-request        # Update via PR

gh aw upgrade

Upgrade repository configuration and agent files

Options:

Examples:

$ gh aw upgrade                              # Full upgrade
$ gh aw upgrade --no-fix --no-compile       # Agent files only
$ gh aw upgrade --create-pull-request       # Upgrade via PR

gh aw remove

Remove workflow and its compiled .lock.yml

$ gh aw remove my-workflow

gh aw enable / gh aw disable

Enable or disable workflows

disable also cancels any in-progress runs automatically.

$ gh aw enable ci-doctor                     # Enable one workflow
$ gh aw disable ci-doctor                    # Disable + cancel active runs
$ gh aw enable                               # Enable all workflows
$ gh aw disable --repo owner/repo            # Disable in a specific repo

🔍 Monitoring & Debugging

gh aw logs

Download and analyze workflow run logs

Downloads and parses logs with tool usage, network patterns, errors, and warnings. Results are cached for 10–100× speedup on subsequent access. Accepts workflow IDs or display names (case-insensitive).

Examples:

$ gh aw logs workflow                        # Download logs
$ gh aw logs -c 10 --start-date -1w         # Last week, 10 results
$ gh aw logs --ref main --parse --json      # Parsed JSON for a branch

gh aw audit

Deep analysis of a specific workflow run

Detailed metrics, tool usage, MCP failures, firewall analysis, no-ops, and artifacts. Accepts run IDs, workflow URLs, job URLs, and step-level URLs. Logs saved to logs/run-{id}/.

Examples:

$ gh aw audit 12345678                                      # By run ID
$ gh aw audit https://github.com/owner/repo/actions/runs/123  # By URL
$ gh aw audit 12345678 --parse                              # Parse to markdown
$ gh aw audit 12345678 --repo owner/repo                    # Specify repo

gh aw health

Workflow health metrics and trends

Displays success rates, trend indicators (↑ improving, → stable, ↓ degrading), execution duration, token usage, costs, and alerts.

Options:

Examples:

$ gh aw health                       # Summary (last 7 days)
$ gh aw health issue-monster         # Detailed for one workflow
$ gh aw health --days 30             # Last 30 days
$ gh aw health --threshold 90 --json # Alert below 90%

gh aw trial

Test workflows in temporary repositories

Tests workflows in temporary private repos (default) or directly in a specified repo. Results saved to trials/.

Examples:

$ gh aw trial githubnext/agentics/ci-doctor          # Test a remote workflow
$ gh aw trial ./workflow.md --logical-repo owner/repo # Act as different repo
$ gh aw trial ./workflow.md --dry-run                # Preview only

🔌 MCP, Secrets & Domains

gh aw mcp

Manage Model Context Protocol (MCP) servers

$ gh aw mcp list workflow                    # List servers for a workflow
$ gh aw mcp list-tools <mcp-server>          # List tools exposed by server
$ gh aw mcp inspect workflow                 # Inspect and test servers
$ gh aw mcp add                              # Add an MCP tool to workflow

gh aw mcp-server

Run gh-aw as an MCP server for IDE integration Bridge

Exposes gh-aw commands as MCP tools — the key bridge between CLI and IDEs. Configure as an MCP tool source in VS Code to give Copilot live access to workflow status, compilation, logs, and audit.

Exposed tools: status, compile, logs, audit, mcp-inspect, add, update

$ gh aw mcp-server                      # stdio transport (default)
$ gh aw mcp-server --port 8080          # HTTP server with SSE
$ gh aw mcp-server --validate-actor     # Enable actor validation

gh aw secrets

Manage repository secrets for AI engine authentication

$ gh aw secrets set MY_SECRET                                    # From stdin
$ gh aw secrets set MY_SECRET --repo myorg/myrepo                # Target repo
$ gh aw secrets set MY_SECRET --value-from-env MY_TOKEN          # From env var

$ gh aw secrets bootstrap                                        # Auto-detect missing
$ gh aw secrets bootstrap --engine copilot                       # Check Copilot only
$ gh aw secrets bootstrap --non-interactive                      # Display, don't prompt

gh aw domains

List network domains referenced in workflows

Shows allowed/blocked domains including DNS expansions.

$ gh aw domains                              # List all domains
$ gh aw domains --json                       # Output in JSON

🧰 Utilities

$ gh aw completion install
$ gh aw completion uninstall

⚙️ Compilation Pipeline

How gh aw compile transforms Markdown into secure GitHub Actions YAML.

File Relationships

.github/
├── workflows/
│   ├── my-workflow.md          ← Source (authored by developer)
│   └── my-workflow.lock.yml    ← Compiled output (generated)
├── aw/
│   └── imports/                  ← Cached remote imports
├── agents/
│   └── agentic-workflows.agent.md  ← Dispatcher agent
└── dependabot.yml              ← Generated with --dependabot

Strict Mode Enforcement

When --strict is enabled, the compiler enforces these security requirements:

💻 IDE Integration

Use gh aw from your favorite editor.

# Works in any terminal
$ gh aw compile --watch
$ gh aw validate --strict
$ gh aw run my-workflow --push

📊 The Agents Tab

A centralized dashboard for managing Copilot coding agent sessions in your repository.

🔁 Local Development Workflow

A typical end-to-end development cycle with gh aw.

# 1. Initialize the repository (one-time setup)
$ gh aw init

# 2. Create a new workflow
$ gh aw new my-workflow --engine copilot

# 3. Edit the .md file in your editor of choice

# 4. Validate without compiling
$ gh aw validate my-workflow

# 5. Compile to .lock.yml
$ gh aw compile my-workflow

# 6. Watch mode for rapid iteration
$ gh aw compile --watch

# 7. Commit both files
$ git add .github/workflows/my-workflow.md .github/workflows/my-workflow.lock.yml
$ git commit -m "Add my-workflow agentic workflow"
$ git push

# 8. Trigger a run
$ gh aw run my-workflow

# 9. Monitor health over time
$ gh aw health my-workflow --days 7

# 10. Analyze a specific run
$ gh aw audit <run-id> --parse

🐛 Debugging & Troubleshooting

Tips, the DEBUG environment variable, and common fixes.

Debug Environment Variable

Enable detailed debugging output with namespace filtering:

$ DEBUG=* gh aw compile                # All debug logs
$ DEBUG=cli:* gh aw compile            # CLI logs only
$ DEBUG=*,-tests gh aw compile         # All except test logs

Fuzzy Workflow Name Matching

The CLI auto-suggests similar workflow names on typos using Levenshtein distance:

$ gh aw compile audti-workflows
✗ workflow file not found
Did you mean: audit-workflows?

GitHub Enterprise Server

$ export GH_HOST="github.enterprise.com"
$ gh auth login --hostname github.enterprise.com
$ gh aw logs workflow --repo github.enterprise.com/owner/repo

Common Issues

📋 Command Cheat Sheet

Every command at a glance.