CLI command implementations for the gh aw extension — the primary user interface for authoring, compiling, running, and monitoring agentic GitHub workflows.

The cli package implements all commands exposed through the gh aw CLI extension. Each command is implemented as a Cobra command with a dedicated New*Command() constructor and a Run*() function that encapsulates the testable business logic.

The package is intentionally decomposed into many small files grouped by feature domain (e.g., compile_*.go, audit_*.go, run_*.go, mcp_*.go). This structure keeps individual files under 300 lines and promotes independent testing of each sub-domain.

Besides Cobra entry points, the package also exposes reusable helpers for workflow resolution, dependency analysis, PR creation, and run auditing so multiple commands can share the same business logic and tests.

All diagnostic output MUST go to stderr using console formatting helpers. Structured output (JSON, hashes, graphs) goes to stdout.

The cli package is intentionally large and command-oriented. The tables below document the most important exported, source-verified entry points and data types rather than every helper. Callers SHOULD treat New*Command() constructors as the stable integration surface for Cobra wiring, and SHOULD use the corresponding Run* or library helpers for programmatic use.

The cli package exports many types used across its command implementations. The following supplements the main "Key Types" table above:

A multi-line string constant (string) containing a user-facing explanation of what a workflow ID is: the basename of the Markdown workflow file without the .md extension.

data, err := cli.CompileWorkflows(ctx, cli.CompileConfig{
    MarkdownFiles: []string{".github/workflows/my-workflow.md"},
    Verbose:       true,
    Validate:      true,
    Strict:        false,
})

err := cli.RunWorkflowOnGitHub(ctx, "my-workflow", cli.RunOptions{
    Repo:    "owner/repo",
    Verbose: true,
})

err := cli.AuditWorkflowRun(ctx, runID, cli.AuditOptions{
    Owner:     "owner",
    Repo:      "repo",
    Hostname:  "github.com",
    OutputDir: "/tmp/output",
    Verbose:   true,
    Parse:     true,
})

err := cli.RunHealth(cli.HealthConfig{
    Pattern:   "*.md",
    Threshold: 0.8,
    Period:    "30d",
})

• File-per-feature decomposition: Large feature domains (compile, audit, logs, run) are split into multiple files (_command.go, _config.go, _helpers.go, _orchestrator.go, etc.) to keep each file focused and under 300 lines.
• Testable Run functions: Every command has a New*Command() for Cobra wiring and a Run*() function with explicit parameters for unit testing without CLI arg parsing overhead.
• Stderr for diagnostics: All user-visible messages use console.Format*Message helpers and write to stderr, preserving stdout for structured machine-readable output.
• Context propagation: Long-running operations accept context.Context to support cancellation (SIGINT, timeouts).
• Config structs: Command options are collected into dedicated *Config or *Options structs rather than passed as long argument lists, improving readability and testability.

Internal:

• github.com/github/gh-aw/pkg/workflow — workflow compilation and data types
• github.com/github/gh-aw/pkg/parser — markdown frontmatter parsing
• github.com/github/gh-aw/pkg/console — terminal output formatting
• github.com/github/gh-aw/pkg/logger — structured debug logging
• github.com/github/gh-aw/pkg/constants — engine names, job names, feature flags
• github.com/github/gh-aw/pkg/agentdrain — Drain log anomaly detection for audit analysis
• github.com/github/gh-aw/pkg/envutil — environment variable reading with bounds validation
• github.com/github/gh-aw/pkg/errorutil — shared error classification helpers for GitHub and gh CLI responses
• github.com/github/gh-aw/pkg/semverutil — semantic version comparison for dependency checks
• github.com/github/gh-aw/pkg/workflow/compilerenv — enterprise compiler-default and timezone override helpers
• github.com/github/gh-aw/pkg/sliceutil — slice utilities
• github.com/github/gh-aw/pkg/stats — incremental statistics for health metrics
• github.com/github/gh-aw/pkg/styles — terminal color styles and lipgloss configuration
• github.com/github/gh-aw/pkg/timeutil — human-readable duration formatting
• github.com/github/gh-aw/pkg/tty — terminal detection
• github.com/github/gh-aw/pkg/types — shared MCP server configuration types
• github.com/github/gh-aw/pkg/typeutil — type conversion helpers for dynamic frontmatter values
• github.com/github/gh-aw/pkg/fileutil — file system helpers
• github.com/github/gh-aw/pkg/gitutil — Git and GitHub CLI helpers
• github.com/github/gh-aw/pkg/repoutil — repository name parsing and normalization
• github.com/github/gh-aw/pkg/stringutil — string manipulation and sanitization utilities
• github.com/github/gh-aw/pkg/syncutil — thread-safe one-shot caching (used for repository slug lookup)
• github.com/github/gh-aw/pkg/github — label-based objective value mapping for issue prioritization scoring
• github.com/github/gh-aw/pkg/intent — intent attribution and resolution for mapping PRs and issues to labelled intent records
• github.com/github/gh-aw/pkg/modelsdev — model pricing lookup backed by the public models.dev catalog
• github.com/github/gh-aw/pkg/setutil — set operations backed by map[K]struct{}
• github.com/github/gh-aw/pkg/colorwriter — color-profile-aware writers and ANSI degradation for terminal output
• github.com/github/gh-aw/pkg/ctxutil — non-nil context.Context fallback for optional context options
• github.com/github/gh-aw/pkg/githubapi — go-gh REST client options with repository-standard defaults

Test-only:

• github.com/github/gh-aw/pkg/testutil — shared test fixtures and assertion helpers used by CLI package tests

External:

• github.com/spf13/cobra — CLI framework
• github.com/cli/go-gh/v2 — GitHub CLI integration

Individual command Run* functions are not concurrently safe unless explicitly documented. The CompileWorkflows orchestrator serializes compilation by default; parallel compilation is gated by CompileConfig flags.

• MCP cache helpers: GetPermission, SetPermission, GetRepo, SetRepo
• HTTP wiring helpers: RoundTrip, WriteHeader
• External scanner helpers: RunGrantOnLockFiles, RunGrypeOnLockFiles, RunSyftOnLockFiles, RunYamllintOnFiles

This appendix is generated from the current non-test Go source files in this package and records any exported top-level symbols that are not already described above.

Method-form symbols on exported types (e.g. (*FileTracker).TrackCreated, (*DomainBuckets).SetAllowedDomains, (*ToolGraph).AddSequence) are already documented in the "Additional functions and methods" table above; the entries here cover only package-level functions that were not yet listed.

Reviewed against recent source updates on 2026-08-08; the "Additional exported top-level functions" table above was added after diffing the full exported-symbol list against this README. No other public-contract deltas were identified beyond the sections above.

This specification is automatically maintained by the spec-extractor workflow.