Skip to content

docs: add "When to use" column to CLI commands summary table#43699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Jul 6, 2026
Merged

docs: add "When to use" column to CLI commands summary table #43699

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1d44b42
Initial plan
Copilot Jul 6, 2026
3851728
docs: add When to use column to CLI summary table
Copilot Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/src/content/docs/setup/cli.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,18 +9,18 @@ The `gh aw` CLI extension enables developers to create, manage, and execute AI-p

## Most Common Commands

| Command | Description |
|---------|-------------|
| [`gh aw init`](#init) | Set up your repository for agentic workflows |
| [`gh aw add-wizard`](#add-wizard) | Add workflows with interactive guided setup |
| [`gh aw add`](#add) | Add workflows from other repositories (non-interactive) |
| [`gh aw new`](#new) | Create a new workflow from scratch |
| [`gh aw compile`](#compile) | Convert markdown to GitHub Actions YAML |
| [`gh aw list`](#list) | Quick listing of all workflows |
| [`gh aw run`](#run) | Execute workflows immediately in GitHub Actions |
| [`gh aw status`](#status) | Check current state of all workflows |
| [`gh aw logs`](#logs) | Download and analyze agentic workflow logs and artifacts |
| [`gh aw audit`](#audit) | Audit and compare workflow runs |
| Command | Description | When to use |
|---------|-------------|-------------|
| [`gh aw init`](#init) | Set up your repository for agentic workflows | First time configuring a repo — creates skills, agents, and `.gitattributes` |
| [`gh aw add-wizard`](#add-wizard) | Add workflows with interactive guided setup | Adding a community workflow and want guided prompts for secrets and auth |
| [`gh aw add`](#add) | Add workflows from other repositories (non-interactive) | Scripted or CI-based workflow installation without interactive prompts |
| [`gh aw new`](#new) | Create a new workflow from scratch | Building a custom workflow when no existing template fits |
| [`gh aw compile`](#compile) | Convert markdown to GitHub Actions YAML | After editing a workflow `.md` file to regenerate the `.lock.yml` |
| [`gh aw list`](#list) | Quick listing of all workflows | Checking which workflows are installed in the current repository |
| [`gh aw run`](#run) | Execute workflows immediately in GitHub Actions | Triggering a workflow run from the command line without opening GitHub |
| [`gh aw status`](#status) | Check current state of all workflows | Verifying workflows are enabled and seeing their last run result |

@github-actionsgithub-actionsBotJul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/grill-with-docs] The entry says "seeing their last run result" but gh aw status only shows run status when --ref is passed — without it you only get enabled/disabled state and schedules.

💡 Suggested wording
|[`gh aw status`](#status)| ... | Verifying workflows are enabled and checking their schedules; add `--ref <branch>` to also see the latest run result |

This sets accurate expectations and surfaces the key flag that unlocks run-history, preventing confusion for new users who don't see run results after their first gh aw status.

@copilot please address this.

@github-actionsgithub-actionsBotJul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Misleading default: "seeing their last run result" requires --ref; bare gh aw status shows no run info and this will confuse beginners.

💡 Suggested fix

The status section states: "With --ref, includes latest run status." — meaning a bare gh aw status shows only state, enabled/disabled, schedules, and labels, but no run results.

A user reading this table entry will run gh aw status, see no run data, and have no idea why.

Suggested rewording:

Checking which workflows are installed and their enabled/disabled state; add --ref <branch> to also see last run status

Or keep it shorter but accurate:

Verifying workflows are enabled (add --ref to also see last run result)

| [`gh aw logs`](#logs) | Download and analyze agentic workflow logs and artifacts | Debugging a past run by inspecting output, tokens used, and artifacts |

@github-actionsgithub-actionsBotJul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/grill-with-docs] The entry says "tokens used" but gh aw logs doesn't report token consumption — that metric lives in gh aw audit.

Looking at the logs section, the command downloads raw logs and surfaces tool usage, network patterns, errors, and warnings. Token counts require gh aw audit.

💡 Suggested wording
|[`gh aw logs`](#logs)| ... | Debugging a past run by inspecting output, tool usage, and downloaded artifacts |

Removing "tokens used" avoids sending users to gh aw logs when they actually need gh aw audit.

@copilot please address this.

| [`gh aw audit`](#audit) | Audit and compare workflow runs | Investigating cost, tool usage, or comparing two runs side-by-side |

> [!TIP]
> New to `gh aw`? You can stop here for day-one usage and jump to [Commands](#commands) when you're ready. The advanced enterprise setup is collapsed below and can be skipped for most users.
Expand Down
Loading