Text of github.github.com › gh-aw › setup › cli as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

CLI Commands | GitHub Agentic Workflows

Skip to main content CLI Commands 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. Day-one commands Section titled “Day-one commands” Command Description When to use gh aw init Set up your repository for agentic workflows First time configuring a repo — creates skills, agents, and .gitattributes gh aw doctor Run repository and authentication diagnostics Verifying gh auth, repo ownership, or local checkout state before setup work gh aw add-wizard Add workflows with interactive guided setup Adding a community workflow and want guided prompts for secrets and auth gh aw add Add workflows from other repositories (non-interactive) Scripted or CI-based workflow installation without interactive prompts gh aw new Create a new workflow from scratch Building a custom workflow when no existing template fits gh aw compile Convert markdown to GitHub Actions YAML After editing a workflow .md file to regenerate the .lock.yml gh aw list Quick listing of all workflows Checking which workflows are installed in the current repository gh aw run Execute workflows immediately in GitHub Actions Triggering a workflow run from the command line without opening GitHub gh aw status Check current state of all workflows Verifying workflows are enabled and seeing their last run result gh aw logs Download and analyze agentic workflow logs and artifacts Debugging a past run by inspecting output, tokens used, and artifacts gh aw audit Audit and compare workflow runs Investigating cost, tool usage, or comparing two runs side-by-side Timeout flag formats Section titled “Timeout flag formats” The --timeout flag uses different formats depending on the command: Command Accepted value Default Example Meaning of 0 audit Go duration 0 --timeout 5m No additional deadline health Go duration 2m --timeout 5m Disables its collection deadline value Positive Go duration 5m --timeout 10m Rejected connector test Go duration greater than zero and at most 20s 20s --timeout 10s Rejected logs episode Go duration 5m --timeout 10m Rejected logs , forecast Integer minutes 0 --timeout 5 No timeout trial Integer minutes 30 --timeout 10 No timeout Utility and advanced commands Section titled “Utility and advanced commands” Command Description When to use gh aw skill Print the bundled agentic-workflows skill Loading instructions into an agent without adding repository files gh aw work-queue Experimental Git-backed DAG work queue Managing queue policy, scheduling, and operator recovery Installation Section titled “Installation” Install the GitHub CLI extension: Terminal window gh extension install github/gh-aw Pinning to a Specific Version Section titled “Pinning to a Specific Version” Pin a version for production environments, team consistency, or to avoid breaking changes: Terminal window 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 Alternative: Standalone Installer Section titled “Alternative: Standalone Installer” If extension installation fails, use the standalone installer instead: Terminal window 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 Terminal window Invoke-WebRequest https: // raw.githubusercontent.com / github / gh - aw / main / install-gh - aw.ps1 - OutFile install-gh - aw.ps1; pwsh - File . / install-gh - aw.ps1 # Latest Invoke-WebRequest https: // raw.githubusercontent.com / github / gh - aw / main / install-gh - aw.ps1 - OutFile install-gh - aw.ps1; pwsh - File . / install-gh - aw.ps1 v0.

1.0 # Pinned This installs to ~/.local/share/gh/extensions/gh-aw/gh-aw and supports Linux, macOS, FreeBSD, Windows, and Android (Termux), including environments behind corporate firewalls. The Bash installer requires sha256sum or shasum and verifies the downloaded binary against the release’s checksums.txt before executing or installing it. Unavailable, missing, malformed, duplicate, or mismatched checksums abort installation and leave any existing binary unchanged.

The explicit --skip-checksum option disables this protection; it is never enabled automatically. GitHub Actions Setup Action Section titled “GitHub Actions Setup Action” In GitHub Actions, use the setup-cli action for platform detection and checksum verification: - 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 full details. Global Options Section titled “Global Options” Flag Description -h , --help Show help ( gh aw help [command] for command-specific help) -v , --verbose Enable verbose output showing detailed information --banner Display ASCII logo banner with purple GitHub color theme --version Print the current version For invalid nested command paths, gh aw now fails explicitly instead of falling back to parent help output.

For example, gh aw secrets gh --help returns an unknown-command error rather than reprinting gh aw secrets help. The --push Flag Section titled “The --push Flag” gh aw run --push stages workflow files (including transitive imports), commits them, and pushes before dispatching the workflow. It refuses to proceed when unrelated files are already staged. For init , update , and upgrade , use --create-pull-request instead.

Commands that create pull requests print the full pull request URL to stderr immediately after creation, including in non-verbose and quiet modes, so terminals can display it as a clickable link. The URL remains visible if subsequent local branch cleanup fails. Pull request descriptions Section titled “Pull request descriptions” init , add , add-wizard , update , upgrade , deploy , and pr transfer include a structured summary and a Generated by gh aw v... footer in created pull requests.

Update and upgrade titles include the gh-aw version used. Their descriptions list dependency pin changes, affected files, a link to the matching gh-aw release, and inline release highlights when available; upgrade also reports the codemods actually applied. Highlights are fenced and labeled as untrusted reference data, not instructions; this boundary is defense in depth, not guaranteed prompt-injection protection. If highlights would exceed GitHub’s description limit, including custom messages, rollout markers, and the footer, only the release link is retained.

Development builds do not link to a release or fetch highlights. Org and enterprise PR rollouts share one release lookup across worker processes for that run. If release lookup fails, the command warns once per rollout and retains the release link. Use --pr-message to append a custom Markdown message without replacing the generated description. The message appears before the version footer and is passed to each created pull request in --repo and --org modes.

This option does not enable PR creation by itself. Large summaries group compiler updates and applied codemods, and show up to 50 changed file paths; the full pin-change list is retained. Descriptions that still exceed GitHub’s 65,536-character limit are rejected before committing or pushing the PR branch. Terminal window gh aw update --create-pull-request --pr-message " Part of the quarterly automation refresh. " gh aw upgrade --org my-org --create-pull-request --yes --pr-message " Tracking issue: #123.

" Pull request auto-merge Section titled “Pull request auto-merge” --auto-merge enables GitHub-native auto-merge on the created pull request. Without this flag, command behavior is unchanged. Commands Options init , add , update , upgrade --auto-merge requires --create-pull-requ

The rest of this page is on the live site.