The gh aw CLI extension enables developers to create, manage, and execute AI-powered workflows directly from the command line. It transforms natural language markdown files into GitHub Actions.

Install the GitHub CLI extension:

gh extension install github/gh-aw

Pin to specific versions for production environments, team consistency, or avoiding breaking changes:

gh extension install github/gh-aw@v0.1.0          # Pin to release tag
gh extension install github/gh-aw@abc123def456    # Pin to commit SHA
gh aw version                                         # Check current version
# Upgrade pinned version
gh extension remove gh-aw
gh extension install github/gh-aw@v0.2.0

Use the standalone installer if extension installation fails (common in Codespaces, restricted networks, or with auth issues):

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

Installs to ~/.local/share/gh/extensions/gh-aw/gh-aw. Supports Linux, macOS, FreeBSD, Windows, and Android (Termux). Works behind corporate firewalls using direct release download URLs.

Install the CLI in GitHub Actions workflows using the setup-cli action with automatic checksum verification and platform detection:

- name: Install gh-aw CLI
  uses: github/gh-aw/actions/setup-cli@main
  with:
    version: v0.37.18

See the setup-cli action README for complete documentation.

Configure for GitHub Enterprise Server deployments:

export GH_HOST="github.enterprise.com"                           # Set hostname
gh auth login --hostname github.enterprise.com                   # Authenticate
gh aw logs workflow --repo github.enterprise.com/owner/repo      # Use with commands

The run command supports --push to automatically commit and push changes before dispatching the workflow. It stages all changes, commits, and pushes to the remote. Requires a clean working directory.

For init, update, and upgrade, use --create-pull-request to create a pull request with the changes instead.

Commands are organized by workflow lifecycle: creating, building, testing, monitoring, and managing workflows.

Initialize repository for agentic workflows. Configures .gitattributes, creates the dispatcher agent file (.github/agents/agentic-workflows.agent.md), and logs .gitignore. Enables MCP server integration by default (use --no-mcp to skip). Without arguments, enters interactive mode for engine selection and secret configuration.

gh aw init                              # Interactive mode: select engine and configure secrets
gh aw init --no-mcp                     # Skip MCP server integration
gh aw init --codespaces                 # Configure devcontainer for current repo
gh aw init --codespaces repo1,repo2     # Configure devcontainer for additional repos
gh aw init --completions                # Install shell completions
gh aw init --create-pull-request        # Initialize and open a pull request

Options: --no-mcp, --codespaces, --completions, --create-pull-request

Add workflows from The Agentics collection or other repositories to .github/workflows.

gh aw add githubnext/agentics/ci-doctor           # Add single workflow
gh aw add "githubnext/agentics/ci-*"             # Add multiple with wildcards
gh aw add ci-doctor --dir shared                  # Organize in subdirectory
gh aw add ci-doctor --create-pull-request        # Create PR instead of commit

Options: --dir, --create-pull-request (or --pr), --no-gitattributes

Create a workflow template in .github/workflows/. Opens for editing automatically.

gh aw new                      # Interactive mode
gh aw new my-custom-workflow   # Create template (.md extension optional)
gh aw new my-workflow --force  # Overwrite if exists

Manage GitHub Actions secrets and tokens.

Create or update a repository secret (from stdin, flag, or environment variable).

gh aw secrets set MY_SECRET                                    # From stdin (current repo)
gh aw secrets set MY_SECRET --repo myorg/myrepo                # Specify target repo
gh aw secrets set MY_SECRET --value "secret123"                # From flag
gh aw secrets set MY_SECRET --value-from-env MY_TOKEN          # From env var

Options: --repo, --value, --value-from-env, --api-url

Analyze workflows to determine required secrets and interactively prompt for missing ones. Auto-detects engines in use and validates tokens before uploading to the repository.

gh aw secrets bootstrap                                  # Analyze all workflows and prompt for missing secrets
gh aw secrets bootstrap --engine copilot                 # Check only Copilot secrets
gh aw secrets bootstrap --non-interactive                # Display missing secrets without prompting

Options: --engine (copilot, claude, codex), --non-interactive, --repo

See Authentication for details.

Auto-fix deprecated workflow fields using codemods. Runs in dry-run mode by default; use --write to apply changes.

gh aw fix                              # Check all workflows (dry-run)
gh aw fix --write                      # Fix all workflows
gh aw fix my-workflow --write          # Fix specific workflow
gh aw fix --list-codemods              # List available codemods

Options: --write, --list-codemods

Notable codemods include expires-integer-to-string, which converts bare integer expires values (e.g., expires: 7) to the preferred day-string format (e.g., expires: 7d) in all safe-outputs blocks. Run gh aw fix --list-codemods to see all available codemods.

Compile Markdown workflows to GitHub Actions YAML. Remote imports cached in .github/aw/imports/.

gh aw compile                              # Compile all workflows
gh aw compile my-workflow                  # Compile specific workflow
gh aw compile --watch                      # Auto-recompile on changes
gh aw compile --validate --strict          # Schema + strict mode validation
gh aw compile --fix                        # Run fix before compilation
gh aw compile --zizmor                     # Security scan (warnings)
gh aw compile --strict --zizmor            # Security scan (fails on findings)
gh aw compile --dependabot                 # Generate dependency manifests
gh aw compile --purge                      # Remove orphaned .lock.yml files

Options: --validate, --strict, --fix, --zizmor, --dependabot, --json, --watch, --purge

Error Reporting: Displays detailed error messages with file paths, line numbers, column positions, and contextual code snippets.

Dependabot Integration (--dependabot): Generates dependency manifests and .github/dependabot.yml by analyzing runtime tools across all workflows. See Dependabot Support reference.

Strict Mode (--strict): Enforces security best practices: no write permissions (use safe-outputs), explicit network config, no wildcard domains, pinned Actions, no deprecated fields. See Strict Mode reference.

Shared Workflows: Workflows without an on field are detected as shared components. Validated with relaxed schema and skip compilation. See Imports reference.

Validate agentic workflows by running the compiler with all linters enabled, without generating lock files. Equivalent to gh aw compile --validate --no-emit --zizmor --actionlint --poutine.

gh aw validate                              # Validate all workflows
gh aw validate my-workflow                  # Validate specific workflow
gh aw validate my-workflow daily            # Validate multiple workflows
gh aw validate --json                       # Output results in JSON format
gh aw validate --strict                     # Enforce strict mode validation
gh aw validate --fail-fast                  # Stop at the first error
gh aw validate --dir custom/workflows       # Validate from custom directory
gh aw validate --engine copilot             # Override AI engine

Options: --engine/-e, --dir/-d, --strict, --json/-j, --fail-fast, --stats, --no-check-update

All linters (zizmor, actionlint, poutine), --validate, and --no-emit are always-on defaults and cannot be disabled. Accepts the same workflow ID format as compile.

Test workflows in temporary private repositories (default) or run directly in specified repository (--repo). Results saved to trials/.

gh aw trial githubnext/agentics/ci-doctor          # Test remote workflow
gh aw trial ./workflow.md --logical-repo owner/repo # Act as different repo
gh aw trial ./workflow.md --repo owner/repo        # Run directly in repository
gh aw trial ./workflow.md --dry-run                # Preview without executing

Options: -e, --engine, --auto-merge-prs, --repeat, --delete-host-repo-after, --logical-repo, --clone-repo, --trigger-context, --repo, --dry-run

Secret Handling: API keys required for the selected engine are automatically checked. If missing from the target repository, they are prompted for interactively and uploaded.

Execute workflows immediately in GitHub Actions. Displays workflow URL for tracking.

gh aw run workflow                          # Run workflow
gh aw run workflow1 workflow2               # Run multiple workflows
gh aw run workflow --repeat 3               # Repeat 3 times
gh aw run workflow --push                   # Auto-commit, push, and dispatch workflow
gh aw run workflow --push --ref main        # Push to specific branch

Options: --repeat, --push (see —push flag), --ref, --auto-merge-prs, --enable-if-needed

When --push is used, automatically recompiles outdated .lock.yml files, stages all transitive imports, and triggers workflow run after successful push. Without --push, warnings are displayed for missing or outdated lock files.

List workflows with basic information (name, engine, compilation status) without checking GitHub Actions state.

gh aw list                                  # List all workflows
gh aw list ci-                              # Filter by pattern (case-insensitive)
gh aw list --json                           # Output in JSON format
gh aw list --label automation               # Filter by label

Options: --json, --label

Fast enumeration without GitHub API queries. For detailed status including enabled/disabled state and run information, use status instead.

List workflows with state, enabled/disabled status, schedules, and labels. With --ref, includes latest run status.

gh aw status                                # All workflows
gh aw status --ref main                     # With run info for main branch
gh aw status --label automation             # Filter by label
gh aw status --repo owner/other-repo        # Check different repository

Options: --ref, --label, --json, --repo

Download and analyze logs with tool usage, network patterns, errors, warnings. Results cached for 10-100x speedup on subsequent runs.

gh aw logs workflow                        # Download logs for workflow
gh aw logs -c 10 --start-date -1w         # Filter by count and date
gh aw logs --ref main --parse --json      # With markdown/JSON output for branch

Workflow name matching: The logs command accepts both workflow IDs (kebab-case filename without .md, e.g., ci-failure-doctor) and display names (from frontmatter, e.g., CI Failure Doctor). Matching is case-insensitive for convenience:

gh aw logs ci-failure-doctor               # Workflow ID
gh aw logs CI-FAILURE-DOCTOR               # Case-insensitive ID
gh aw logs "CI Failure Doctor"             # Display name
gh aw logs "ci failure doctor"             # Case-insensitive display name

Options: -c, --count, -e, --engine, --start-date, --end-date, --ref, --parse, --json, --repo

Analyze specific runs with overview, metrics, tool usage, MCP failures, firewall analysis, noops, and artifacts. Accepts run IDs, workflow run URLs, job URLs, and step-level URLs. Auto-detects Copilot coding agent runs for specialized parsing. Job URLs automatically extract specific job logs; step URLs extract specific steps; without step, extracts first failing step.

gh aw audit 12345678                                      # By run ID
gh aw audit https://github.com/owner/repo/actions/runs/123 # By workflow run URL
gh aw audit https://github.com/owner/repo/actions/runs/123/job/456 # By job URL (extracts first failing step)
gh aw audit https://github.com/owner/repo/actions/runs/123/job/456#step:7:1 # By step URL (extracts specific step)
gh aw audit 12345678 --parse                              # Parse logs to markdown

Logs are saved to logs/run-{id}/ with filenames indicating the extraction level. Pre-agent failures (lockdown validation, missing secrets, binary install) surface the actual error in failure_analysis.error_summary. Invalid run IDs return a human-readable error.

Display workflow health metrics and success rates.

gh aw health                       # Summary of all workflows (last 7 days)
gh aw health issue-monster         # Detailed metrics for specific workflow
gh aw health --days 30             # Summary for last 30 days
gh aw health --threshold 90        # Alert if below 90% success rate
gh aw health --json                # Output in JSON format
gh aw health issue-monster --days 90  # 90-day metrics for workflow

Options: --days, --threshold, --repo, --json

Shows success/failure rates, trend indicators (↑ improving, → stable, ↓ degrading), execution duration, token usage, costs, and alerts when success rate drops below threshold.

Enable one or more workflows by ID, or all workflows if no IDs provided.

gh aw enable                                # Enable all workflows
gh aw enable ci-doctor                      # Enable specific workflow
gh aw enable ci-doctor daily                # Enable multiple workflows
gh aw enable ci-doctor --repo owner/repo    # Enable in specific repository

Options: --repo

Disable one or more workflows and cancel any in-progress runs.

gh aw disable                               # Disable all workflows
gh aw disable ci-doctor                     # Disable specific workflow
gh aw disable ci-doctor daily               # Disable multiple workflows
gh aw disable ci-doctor --repo owner/repo   # Disable in specific repository

Options: --repo

Remove workflows (both .md and .lock.yml).

Update workflows based on source field (owner/repo/path@ref). By default, performs a 3-way merge to preserve local changes; use --no-merge to override with upstream. Semantic versions update within same major version.

By default, update also force-updates all GitHub Actions referenced in your workflows (both in actions-lock.json and workflow files) to their latest major version. Use --disable-release-bump to restrict force-updates to core actions/* actions only.

If no workflows in the repository contain a source field, the command exits gracefully with an informational message rather than an error. This is expected behavior for repositories that have not yet added updatable workflows.

gh aw update                              # Update all with source field
gh aw update ci-doctor                    # Update specific workflow (3-way merge)
gh aw update ci-doctor --no-merge         # Override local changes with upstream
gh aw update ci-doctor --major --force    # Allow major version updates
gh aw update --disable-release-bump       # Update workflows; only force-update core actions/*
gh aw update --create-pull-request        # Update and open a pull request

Options: --dir, --no-merge, --major, --force, --engine, --no-stop-after, --stop-after, --disable-release-bump, --create-pull-request

Upgrade repository with latest agent files and apply codemods to all workflows.

gh aw upgrade                              # Upgrade repository agent files and all workflows
gh aw upgrade --no-fix                     # Update agent files only (skip codemods)
gh aw upgrade --create-pull-request        # Upgrade and open a pull request
gh aw upgrade --audit                      # Run dependency health audit
gh aw upgrade --audit --json               # Dependency audit in JSON format

Options: --dir, --no-fix, --no-actions, --create-pull-request, --audit, --json

Manage MCP (Model Context Protocol) servers in workflows. mcp inspect auto-detects safe-inputs.

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

See MCPs Guide.

Transfer pull request to another repository, preserving changes, title, and description.

gh aw pr transfer <pr-url> --repo target-owner/target-repo

Run MCP server exposing gh-aw commands as tools. Spawns subprocesses to isolate GitHub tokens.

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

Options: --port (HTTP server port), --cmd (custom subprocess command), --validate-actor (enforce actor validation for logs and audit tools)

Available Tools: status, compile, logs, audit, mcp-inspect, add, update

When --validate-actor is enabled, logs and audit tools require write+ repository access via GitHub API (permissions cached for 1 hour). See MCP Server Guide.

Show gh-aw version and product information.

Generate and manage shell completion scripts for tab completion.

gh aw completion install              # Auto-detect and install
gh aw completion uninstall            # Remove completions
gh aw completion bash                 # Generate bash script
gh aw completion zsh                  # Generate zsh script
gh aw completion fish                 # Generate fish script
gh aw completion powershell           # Generate powershell script

Subcommands: install, uninstall, bash, zsh, fish, powershell. See Shell Completions.

Create and manage GitHub Projects V2 boards.

Create a new GitHub Project V2 owned by a user or organization with optional repository linking.

gh aw project new "My Project" --owner @me                      # Create user project
gh aw project new "Team Board" --owner myorg                    # Create org project
gh aw project new "Bugs" --owner myorg --link myorg/myrepo     # Create and link to repo

Options:

• --owner (required): Project owner - use @me for current user or specify organization name
• --link: Repository to link project to (format: owner/repo)

Token Requirements:

Compute a deterministic SHA-256 hash of workflow frontmatter for detecting configuration changes.

gh aw hash-frontmatter my-workflow.md
gh aw hash-frontmatter .github/workflows/audit-workflows.md

Includes all frontmatter fields, imported workflow frontmatter (BFS traversal), template expressions containing env. or vars., and version information (gh-aw, awf, agents).

Enable tab completion for workflow names, engines, and paths. After running gh aw completion install, restart your shell or source your configuration file.

# Bash
gh aw completion bash > ~/.bash_completion.d/gh-aw && source ~/.bash_completion.d/gh-aw
# Zsh
gh aw completion zsh > "${fpath[1]}/_gh-aw" && compinit
# Fish
gh aw completion fish > ~/.config/fish/completions/gh-aw.fish
# PowerShell
gh aw completion powershell | Out-String | Invoke-Expression

Enable detailed debugging with namespace, message, and time diffs.

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

Use --verbose flag for user-facing details.

Auto-suggests similar workflow names on typos using Levenshtein distance.

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

Works with: compile, enable, disable, logs, mcp commands.

See Common Issues and Error Reference for detailed troubleshooting.

• Quick Start - Get your first workflow running
• Frontmatter - Configuration options
• Reusing Workflows - Adding and updating workflows
• Security Guide - Security best practices
• MCP Server Guide - MCP server configuration
• Agent Factory - Agent factory status