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.

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

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, "owner", "repo", "github.com",
    "/tmp/output", true, true, false, 0, 0, nil)

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:

• pkg/workflow — workflow compilation and data types
• pkg/parser — markdown frontmatter parsing
• pkg/console — terminal output formatting
• pkg/logger — structured debug logging
• pkg/constants — engine names, job names, feature flags
• pkg/stringutil, pkg/fileutil, pkg/gitutil, pkg/repoutil — utilities

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.

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