Skip to content

Repository navigation

cao-cli.md

Latest commit

 

History

History
1219 lines (1038 loc) · 72.3 KB

cao-cli.md

File metadata and controls

1219 lines (1038 loc) · 72.3 KB
Raw
title CAO Commands
description Configure, inspect, and query CAO with the native Go extension.
agent
type prominent
cli-reference
true

Use the compiled Go extension as gh cao for operator commands and read-only evidence analysis. The former Activity JavaScript runtime and its Node-only commands have been removed; there is no shell launcher or compatibility entry point. Workflow agents may use an explicitly installed gh cao, or the bounded read-only GitHub and agentic-workflow tools already available to them. Server hosting and administration belong to cao-dashboard.

Follow the cao-cli skill for command ownership and analyze-cao for evidence interpretation. Run policy commands from the control repository root. Use gh cao --help and gh cao COMMAND --help for the supported surface. Failures exit nonzero without substituting a retired runtime.

Operator evidence

On-demand local dashboard

For a short investigation, use the installed extension without running setup, installing Actions, or creating CAO policy:

gh cao dashboard
gh cao dashboard --repo octo/api
gh cao dashboard --repo octo/api --repo octo/web

Release binaries embed the pinned gh-aw log collector, the existing Go server, and the built dashboard. Use an authenticated GitHub CLI and Docker or Podman; there is no separate gh-aw, Node.js, npm, or Redis setup. Without an explicit --postgres-url or CAO_POSTGRES_URL, the command pulls and starts an owned PostgreSQL container and provisions separate owner/runtime roles. Its data is bind-mounted under the ignored .github/cao/dashboard/<scope>/postgres/ cache. Docker is tried first, then Podman; --container-engine docker|podman (or CAO_CONTAINER_ENGINE) selects one engine exclusively. An explicit connection bypasses container management and requires pre-provisioned storage. By default, all dashboard code, static assets, query contracts, and the canonical artifact normalizer come from the installed extension binary, not a CAO checkout or separately installed runtime files. Existing GitHub CLI configuration and authentication are honored, as are optional local gh-aw artifact caches and explicit source-development overrides described below; none requires installing separate CAO runtime files. The command extracts its bundled resources to a private temporary directory and removes them on shutdown; only the local evidence cache is retained. Release installation checks start the dashboard from an empty directory with the required native executables and exercise its embedded collector, HTTP assets, and PostgreSQL queries. The command resolves the current repository when --repo is omitted and supports up to 20 explicitly named GitHub.com repositories.

The evidence window defaults to seven days (maximum 168h); server lifetime defaults to 48 hours, which remains its maximum per invocation. The command stays in the foreground, selects an available loopback port, prints the access URL, and collects in background passes separated by five minutes. The server starts without waiting for artifact downloads. Startup displays a clearly labelled browser URL, repository scope, canonical cache path, refresh interval, and session lifetime. The ready message also reminds you that Ctrl-C stops the server without deleting the cache. If repository access fails, check gh auth status --hostname github.com in the same terminal that runs the command. Ctrl-C closes its server and stops collection. --listen 127.0.0.1:8443, --window 12h, --duration 2h, --refresh 2m, and --count 100 narrow or adjust the session. The count caps each repository's recent-run lookup and cached usage sample separately (maximum 1000 each); historical pages contain at most 100 runs. One repository is processed per pass in round-robin order. Fixed date intervals and saved page checkpoints let later passes reach older history rather than repeatedly sampling only the newest runs. Dense intervals are split before reaching GitHub's 1000-result filtered-search ceiling. Earlier pages remain in PostgreSQL until they age out of the selected window; restarting reuses the saved checkpoint. Discovery completion is not a guarantee of complete artifacts or upstream coverage.

The header's data-status card shows a history progress bar, compact API headroom and a retry countdown. On mobile, tap the labeled menu button to open its popup; desktop keeps a hover tooltip. Details expands diagnostics and timestamps. This status updates through the ordinary server revision subscription without navigation, and ignores page filters. Scanned hours measure completed history-discovery intervals, not the percentage of runs or artifacts acquired. Acquisition shares a ceiling of 100 core API points per pass and reserves at least 1000 points or 20% of the reported core limit, whichever is greater. Exhausted headroom pauses acquisition instead of spending the reserve; later passes recheck quota and resume. GitHub clients using the same credentials share this quota, so concurrent external traffic can reduce the available headroom. Unknown quota fails closed.

The CLI binds verified canonical JSONL to the ordinary cao-dashboard serve --source DIRECTORY mode. It uses the standard built-in dashboard, server HTTP/query API, and PostgreSQL backend, without a separate local presentation model, query aliases, or local-preview routing. It does not discover or load legacy campaign dashboard bundles. Acquisition and canonical publication use the production Go ingestion boundary; the HTTP server reads consistent PostgreSQL transactions and observes committed revisions. The landing page remains the standard Overview, with the existing factory header, factory stations, normal navigation and drill-downs. The shared Runs page presents recent executions and daily observations through canonical PostgreSQL and revision subscriptions, not browser IndexedDB. Its local daily projection reconciles observed logical Runs by UTC execution-start day in the same atomic publication transaction. Replays and reruns do not double count, and compact receipts retain observations independently of the seven-day detail window under the canonical three-week retention policy. Undated evidence is excluded and reported as incomplete; whole-day counts are partial observations, not exhaustive or exact sub-day totals. It combines fresh Actions status with cached gh-aw evidence and requests all available artifact sets, including audit evidence. The existing production gh-aw adapter and canonical normalizer hydrate jobs, sessions, tool calls, firewall domains, skills, friction, safe outputs, experiments, evals and graders when their evidence is available. Only agentic .lock.yml workflows are included. The normal operational dashboard remains available, including repository, workflow and run drill-downs. Ordinary server capability checks govern administration and maintenance; no local-specific pages or query substitutions are installed. Rich artifact views remain available, with explicit partial or unavailable evidence when artifacts are missing. Campaign policy, fleet queue backlog, accepted outcomes and Operational Value are not inferred from run success. Coverage is partial: uncollected evidence must never appear as healthy zeros. Successful executions are not verified outcomes.

Canonical artifacts and per-repository caches are retained under the ignored .github/cao/dashboard/ directory, keyed by exact repository scope. --cache-dir PATH selects another private directory; do not point it at an existing Activity database. --repo may target any accessible github.com repository from any folder. When the single selected repository is the current checkout's repository, an existing .github/aw/logs artifact cache is reused automatically; other targets use a profile-owned cache. Select an external cache explicitly with --logs-dir PATH. Existing gh-aw artifacts and matching cached JSONL records are reused by the same gh-aw collector. Only profile-owned artifact caches receive the 256 MiB storage budget; existing external gh-aw caches are not pruned by this command. Collection selects exact remote workflow IDs from the Actions inventory and observed runs, so it does not depend on workflow files in the current folder. Its rich-run budget is shared across those observed workflows under one two-minute deadline and the pass's API ceiling; reaching this acquisition limit is reported and publishes partial collected evidence. Refresh reuses analyses and artifacts, but fetches fresh run-discovery lists rather than replaying a stale open-ended cached listing. Older profile-owned run directories may be pruned to enforce the artifact budget; external caches are never pruned. Canonical parsing runs inside the native CLI, without invoking gh-aw's optional Node-based Markdown report parsers. Artifact normalization reads only selected matching-attempt run directories, rejects symlinks and nonregular files, and limits each admitted file to 16 MiB and each repository's artifact input to 32 MiB. Oversized or malformed evidence fails the refresh rather than publishing a truncated success. Cache files can contain private repository evidence; protect directory ACLs on Windows, where POSIX mode bits are not sufficient. A failed refresh preserves previously published evidence and its history checkpoint; a separate status update reports the failure rather than replacing evidence with empty data.

gh cao dashboard only serves the dashboard; it has no subcommands. Collection and refresh happen automatically while it is running. Maintenance controls use a separate private, durable command queue, not the canonical snapshot. They accept only declared gh-aw maintenance actions for the exact --repo scope, require pull-request publication, and ask for approval in the owning terminal before each execution. The pinned gh-aw maintenance commands run inside the native CLI using the operator's GitHub CLI identity; credentials never reach the read-only Go dashboard host. Closing output only detaches; canceling a command terminates its owned process tree. Retries require fresh terminal approval. Without a trusted interactive terminal, execution fails closed. Native approval is currently supported on Unix; Windows cannot execute these actions. No maintenance command runs merely because the dashboard starts, and this mode does not mutate remote runs, dispatch workflows, change rollout policy or enable hosted execution. The native adapter is independent of canvas integration. Its normal server endpoints require bearer authentication and same-origin mutation requests in addition to fresh terminal approval.

For source development, build the server and site and pass both --server-executable PATH and --site PATH. Release builds package these assets automatically; source builds deliberately do not fetch or build tools at runtime.

Release evidence

gh cao evidence groups read-only operator evidence collection. The initial release subcommand reuses existing package/promotion workflow runs and optional Azure deployment receipts; it does not build, publish, promote, deploy, change authority, or configure evidence retention. It runs entirely in Go with no Node.js or repository checkout required:

gh cao evidence release \
  --repo githubnext/gh-cao \
  --revision FULL_40_CHARACTER_SOURCE_SHA \
  --image ghcr.io/githubnext/gh-cao/cao-server@sha256:EXACT_64_CHARACTER_DIGEST \
  --package-run PACKAGE_RUN_ID \
  --output /secure/evidence/release-evidence.json

Optionally add --promotion-run RUN_ID, --azure-receipt PATH, or --verify-provenance. The last option invokes gh attestation verify with exact source/image/reusable-publisher constraints and requires the package run attempt to match. Existing GitHub/registry read authentication is required; do not put credentials in arguments. The new output uses mode 0600 where supported and is never overwritten; operators must restrict destination-directory ACLs, especially on Windows where POSIX mode bits do not enforce private access. GitHub.com/GHCR are currently supported. Errors exit nonzero; optional unavailable evidence stays unknown in the JSON.

The report always remains incomplete: approval references do not establish independent approval, configured Azure image read-back is not measured running image identity, and local source-built Azure images remain development-only. Owners must retain original artifacts, signed bundles and verification receipts through their approved evidence channel and supply independent retention, governance and examination-period evidence. See the release evidence boundaries. This command requires an extension release containing it; merging source alone does not update an installed binary.

GitHub CLI extension

Install the extension with GitHub CLI, then run guided setup from an existing control-repository checkout's root:

gh extension install githubnext/gh-cao
gh cao --version
gh cao setup

:::tip[SAML-token installation failure] If gh extension install fails because your token lacks cross-organization SAML authorization, use the curl installer:

curl -fsSL https://raw.githubusercontent.com/githubnext/gh-cao/main/install-gh-cao.sh | bash -s -- --setup

This fallback requires Bash, curl, Git, Node.js 24+, and GitHub CLI 2.68+ signed in for the control repository. Public tool downloads are anonymous; stored credentials remain available for control-repository and runtime-provenance access. :::

GitHub CLI release discovery

CAO releases include native binaries for GitHub CLI discovery. There is intentionally no root executable script: CAO ships a standalone Go binary, not a source-building or Node.js launcher. GitHub CLI classifies the extension using releases/latest before selecting a --pin tag, so maintainers must keep complete native assets in the latest stable release. Do not modify immutable historical releases to repair discovery.

Refresh a GitHub-CLI-managed extension with:

gh extension upgrade gh-cao
gh cao --version

Rerun install-gh-cao.sh only for an installer-managed extension.

Extension installation alone does not install the control-repository runtime or gh-aw. gh cao setup prepares them as needed. Upgrade the extension to receive new commands and fixes; merging source does not update an installed binary.

Guided runtime preparation

gh cao setup runs from an existing GitHub checkout's root. It prepares missing monitoring runtime files and missing baseline policy, then configures exact repository scope and authentication. It does not configure Pages or ask for public-publication consent. It stages the root package with gh-aw in an isolated checkout, verifies the selected stable release's exact runtime provenance and file checksums, and checks all destinations before adding files. Existing policy is read, not replaced with a baseline. Invalid policy and conflicting runtime files fail closed. Complete runtime installs are reused; use gh cao update --campaign root for upgrades.

Control repositories receive the reviewed dashboard and shared control resources, dashboard/, and .github/, not tests, screenshots, contributor tooling, or plugin files. Normal materialization downloads a prebuilt exact-SHA archive, without install-time npm. Stable versions use release assets; main/SHA installs use successful Actions artifacts retained for 90 days, waiting at most five minutes for an already active exact-SHA runtime build. Artifact and attestation access needs authenticated GitHub CLI even when public tool downloads are anonymous. See the runtime provenance contract. Dashboard builds still install their production npm dependencies.

Missing gh-aw is installed at the selected catalog's minimum version. Setup never silently upgrades an existing older or broken extension. It does not need Node.js locally. gh cao init remains an optional, policy-only local preparation command for scripting; it is not a prerequisite and does not configure remote settings. Both paths construct the same exact, campaign-free baseline policy.

Create or clone repositories explicitly with gh repo create or gh repo clone before setup. Setup never creates repositories, enrolls campaigns, or dispatches workflows. A failed or cancelled setup can leave prepared runtime files and already applied credential settings; inspect them before retrying. After approval, brief progress lines identify each setup step before it starts, including release download, workflow preparation, authentication, and policy saving. Progress goes to stderr, keeping --json stdout machine-readable.

Interactive setup offers a separate “Commit and push these CAO monitoring changes? [y/N]” after configuration. It shows a one-line change summary, with additions in green and deletions in red when terminal color is enabled. The complete diff is in a temporary file available while the prompt is open; file-by-file statistics and the policy patch are not printed inline. Review uses an isolated Git index and does not stage your files. Only the exact runtime/package files prepared by this setup and policy are eligible, never unrelated files, including files alongside the runtime.

Approval requires an empty real index, a matching single origin push destination, and a default-branch checkout exactly synchronized with the remote (or both unborn for an empty repository). Setup rechecks Git/file state after review, commits the reviewed changes, and pushes normally without force, extra tags, submodule pushes, or protection bypasses. Existing local commits, staged changes, feature branches, or uncommitted runtime from an earlier setup require manual publication. Commit failures leave staging for inspection; push failures retain the local commit with recovery guidance.

Success reports Actions and known dashboard URLs as deployment pending and returns immediately: no workflow dispatch, polling, or deployment wait. Interactive color output separates the success message from the prompt, highlights the link labels, and underlines the URLs. Redirected, no-color, and accessible output stays plain. --json includes publication.status and, after a push, its commit, links, and deploymentStatus: "pending". Declining or cancelling publication leaves configuration local. Unattended/CI setup never commits or pushes.

Linear, Jira, and Azure DevOps webhook setup

gh cao setup linear, gh cao setup jira, and gh cao setup ado (azure-devops is an alias) prepare an existing webhook gateway to receive issue-service events. These native commands work offline and print service configuration instructions and a secret-free gateway enrollment fragment. They do not provision a gateway, register a webhook with the provider, modify policy, upload credentials, or activate workflows.

Supply your existing public HTTPS gateway URL, a unique source route, the provider's canonical resource prefix and native scope, exact destination GitHub numeric repository IDs, and an explicit future expiry:

gh cao setup linear \
  --gateway-url https://hooks.example.com \
  --source-id linear-acme \
  --resource-url-prefix https://linear.app/acme/issue/ \
  --scope LINEAR_ORGANIZATION_ID \
  --destination-repository-id 123456789 \
  --expires-at 2030-01-01T00:00:00Z

gh cao setup jira \
  --gateway-url https://hooks.example.com \
  --source-id jira-app \
  --resource-url-prefix https://example.atlassian.net/rest/api/3/issue/ \
  --scope APP \
  --destination-repository-id 123456789 \
  --expires-at 2030-01-01T00:00:00Z

gh cao setup ado \
  --gateway-url https://hooks.example.com \
  --source-id ado-app \
  --resource-url-prefix https://dev.azure.com/acme/_apis/wit/workItems/ \
  --scope AZURE_PROJECT_ID \
  --collection-id AZURE_COLLECTION_ID \
  --destination-repository-id 123456789 \
  --expires-at 2030-01-01T00:00:00Z \
  --json --output /secure/deployment/ado-webhook-setup.json

Replace all example identities and choose a suitably bounded expiry. Repeat --destination-repository-id for multiple explicitly approved destinations. --json emits the preparation report for automation; --output saves it to a new mode-0600 file without overwriting files or symlinks. Its parent directory must exist; restrict directory ACLs too, especially on Windows. --dry-run never creates that file. No provider API token or webhook secret is accepted as a flag or included in the report.

Complete the printed instructions in the provider's administration interface:

Service Webhook configuration gh-aw trigger Matching safe outputs
Linear Workspace settings → API → Webhooks; select Issue events and the intended workspace/team scope. Use the generated receiver URL. Preserve Linear-Signature, Linear-Delivery and the signed webhookTimestamp; the receiver requires timestamp freshness within one minute. linear_issue, scoped by organization-id linear-create-issue, linear-update-issue, linear-add-comment
Jira Jira administration → System → WebHooks; select issue created/updated/deleted events and restrict the project. Configure a webhook secret and ensure signed deliveries include X-Hub-Signature: sha256=… and X-Atlassian-Webhook-Identifier. Unsigned webhook configurations are unsupported. jira_issue, scoped by project jira-create-issue, jira-update-issue, jira-add-comment, jira-add-label
Azure DevOps Project settings → Service hooks → Web Hooks; create subscriptions for workitem.created, workitem.updated, and workitem.deleted in the intended project. Configure HTTPS Basic authentication with username cao and a dedicated receive-only password. azure_devops_issue, scoped by project_id ado-create-work-item, ado-update-work-item, ado-comment-on-work-item, ado-assign-work-item, ado-link-work-items, ado-upload-workitem-attachment

Store the provider signing secret (or Azure hook password), 32–512 bytes, only in the receive deployment's secret manager under the generated CAO_GATEWAY_SOURCE_… name. --secret-env selects another valid receive-only name. Optional rotation uses the corresponding _PREVIOUS environment name. Never reuse outbound API credentials or place secret values in policy, generated reports, command arguments, workflow inputs, or committed files.

Review and merge the generated source entry into the gateway policy's externalSources, preserving existing entries, choosing unique source IDs and secret names, and advancing the reviewed policy revision. This is gateway enrollment, not a replacement for .github/workflows/cao.json. Enroll each destination independently in managed discovery; the gateway requires fresh, approved compiled workflow inventory and private destinations. Restart the receiver after adding a source. Deploy the receiver and dispatch roles with their separately scoped credentials and durable operational storage before testing delivery. GitHub Pages is not a webhook receiver.

In the destination workflow, declare the matching scoped gh-aw trigger and only the safe outputs required by its mission. Configure outbound credentials separately in GitHub Actions secrets:

  • Linear: LINEAR_API_KEY; issue creation also needs a trusted team-id or LINEAR_TEAM_ID secret. An optional project can be fixed by project-id or the LINEAR_PROJECT_ID variable.
  • Jira: JIRA_USER_EMAIL and JIRA_API_TOKEN. Explicitly set your own trusted JIRA_BASE_URL through safe-outputs.env; never rely on an upstream example tenant.
  • Azure DevOps: AZURE_DEVOPS_EXT_PAT by default, or an explicitly configured supported SYSTEM_ACCESSTOKEN. Fix the intended organization/project and output targets in reviewed workflow configuration.

These names map to gh-aw v0.92.0; consult your installed compiler's safe-output reference for destination options and limits. Compile changed workflows, review the generated locks, and keep rollout in review mode unless separately authorized. Neither receiving a webhook nor possessing a provider token grants CAO authority. Test a real scoped event, check provider delivery status and gateway admission, then verify the intended workflow and declared output. Setup reports preparation only, never successful delivery or live provider access. See the external-source gateway contract for authentication, normalization, expiry and dispatch requirements.

Optional ADX destination setup

gh cao setup adx prepares the existing hosted server's snapshot-only ADX integration. It runs offline without Node.js, Azure CLI, a checkout, or GitHub authentication. Supply an existing public-cloud Kusto query endpoint/database, Entra application identity and exact canonical repository IDs already collected in your CAO namespace, not repository names to resolve or wildcard scope:

gh cao setup adx \
  --endpoint https://CLUSTER.REGION.kusto.windows.net \
  --database CaoAnalytics \
  --tenant-id 11111111-1111-1111-1111-111111111111 \
  --client-id 22222222-2222-2222-2222-222222222222 \
  --repository-id EXACT_CANONICAL_REPOSITORY_ID \
  --data-approved --single-replica \
  --output /secure/deployment/adx-environment.json

Replace the example identity and scope with reviewed values. Repeat --repository-id for up to 1,000 unique IDs. Explicit --data-approved acknowledges that the corpus/use and actual destination meet applicable service terms, privacy and governance; --non-personal-data is the alternative approval for non-personal, non-regulated data. --single-replica confirms exactly one exporter, durable operational state and a persistent worker lifecycle. These acknowledgments do not verify suitability, authority, topology or access.

Stdout is always a JSON environment object with string values, including CAO_ADX_ENABLED=true and explicit trace/mining disables. --output additionally creates that object as a new mode-0600 file, never overwriting existing files or symlinks; its parent directory must exist. Restrict directory ACLs as well, especially on Windows where POSIX modes do not enforce private access. --dry-run prints the same settings but never creates the output file. No ambient ADX settings or credentials are read. Optional --interval defaults to 30s (range 1s–1h) and --max-storage-bytes defaults to 50,000,000,000 (range 1 MiB–1 TiB).

Review and apply cao-dashboard adx schema to the destination separately before deployment. Map the JSON keys to environment settings in your existing single-replica hosted PostgreSQL deployment; this is not a shell script or gh cao deploy azure configuration file, and setup does not apply it. Inject the omitted CAO_ADX_CLIENT_SECRET directly from the deployment secret manager, never a flag, reviewed policy, or committed document. The generated profile intentionally disables any existing traces/mining when applied; separate trace enablement requires its own reviewed scope, content/rights approvals and durable spool configuration. No resources, schema, credentials, policy, collection, deployment, live traces, mining or model training are changed by this command. See the ADX operator contract and trace contract.

Control-plane installer

Use the root installer as a fallback when SAML-restricted tokens prevent GitHub CLI extension installation:

curl -fsSL https://raw.githubusercontent.com/githubnext/gh-cao/main/install-gh-cao.sh | bash

The installer registers gh cao directly in GitHub CLI's data directory, following the gh-aw installer pattern, without requiring Go or a repository rename. It honors XDG_DATA_HOME and Windows LOCALAPPDATA, defaulting to ~/.local/share/gh/extensions/gh-cao. Rerun the installer to update this manually installed extension; gh extension upgrade does not manage it. Linked/source installations are not overwritten. Release binaries use the gh-cao-OS-ARCH naming convention, with .exe for Windows, and cover Linux, macOS, and Windows on amd64 and arm64. checksums.txt contains their SHA-256 digests. Downloads fail closed unless the asset's exact checksum and embedded version match. Verification finishes before replacing an existing binary. It installs gh aw using the upstream install-gh-aw.sh, passing the required version and keeping upstream checksum verification enabled. The upstream installer runs without token environment variables or the Actions INPUT_VERSION override that would select authenticated extension installation. Public CAO release metadata, binaries, checksums, and the upstream installer are fetched anonymously, ignoring curl configuration that could inject authentication. No credentials are cleared from the parent environment, GitHub CLI configuration, or keychain. Authenticated control-repository creation and setup retain the operator's sign-in. Anonymous API rate limits or network errors fail closed; they do not trigger an authenticated download fallback. An explicit catalog source githubnext/gh-cao@vX.Y.Z selects the same extension tag, including a published prerelease with that tag; otherwise the installer selects the latest published CAO vX.Y.Z release, including prereleases but excluding drafts. Main/SHA and local catalog sources still select their own runtime revision independently. Node.js 24+ is required by this installer, but not by native setup or the other Go operator commands.

Command reference

For local development, build with make build and use ./gh-cao directly, or follow the local extension installation guide to invoke it as gh cao.

Surface Commands Execution
Policy and workflow controls init, campaigns mode, campaigns enable, campaigns disable Native Go; init is optional local policy-only preparation, not runtime, Pages, or credential setup.
Standalone workflow installation add WORKFLOW [--force] [--engine ENGINE] gh-aw installs and compiles; CAO registers the standalone workflow in policy. Interactive publication and first run require separate default-No approvals.
Campaign installation add CAMPAIGN [GH_AW_ADD_OPTIONS...] Native Go; gh-aw owns installation records and workflow generation, Go materializes campaign resources and merges policy. No Node runtime required.
Onboarding and authentication setup, setup auth github-app|enterprise-app|hosted-cli|token Native Go; setup prepares missing monitoring runtime and policy, scope, and authentication, preserving separate read/write and hosted-executor credentials. It does not configure Pages.
Issue-service webhook setup setup linear, setup jira, setup ado (alias setup azure-devops) Native Go; offline enrollment preparation and provider instructions, with separate receive secrets and outbound safe-output credentials.
Cooperative admission setup admission, admission status, admission disable Native Go; configure admission with setup admission. Configures or inspects non-secret Actions variables, not server deployment or enrollment authority.
Cloud deployment deploy azure Native Go; shared TOSCA dependency resolution with an embedded Azure template, read-only preflight and planning, or explicit application of a reviewed development deployment plan.
Deployment bundles deploy init, deploy generate, deploy check Native Go; offline resolution of generated TOSCA 1.3 requirement graphs, embedded review-only Bicep bundles, Mermaid manifests and dependency/drift checking. No deployment or App changes. See bundle generation.
Lifecycle repos add OWNER/REPO, update, upgrade-gh-aw Native Go; gh-aw still owns workflow generation and campaign installation records.
Read-only analysis download, pages, queries, query-info, prompt, query, gh runs|issues|prs, computation intelligence|runtime-health, api-cost, mcp Native Go using PostgreSQL canonical read sessions, hosted queries where declared, and declarative Dashboard Language evaluation.
Workflow value value publish, value enable, value disable Publish prepared evidence to a hosted dashboard, or edit reviewed local policy for recurring collection of one workflow.
Operator evidence evidence release Native Go; bounded read-only GitHub references, optional provenance verification and development Azure receipt summaries. No Node runtime or checkout required.
On-demand dashboard dashboard Native Go; bounded collection with automatically managed local Docker/Podman PostgreSQL unless a connection is specified. No remote mutations, policy, Actions, or runtime installation.
Installation diagnostics doctor, version Native Go. doctor checks GitHub CLI, gh-aw, authentication, and basic local policy structure and compiler pin.
Workflow-agent evidence APIs download, pages, queries, query-info, prompt, query, gh runs|issues|prs, computation intelligence|runtime-health, mcp Supported gh cao COMMAND APIs inside agentic workflows, including their installed runtime dependencies; intentional overlap with operator reads, not deprecated duplicates.
Canonical artifact import cao-dashboard ingest --source DIRECTORY Explicit verified canonical JSONL ingestion into provisioned PostgreSQL; no raw-log database conversion.
Dashboard maintenance scripts/dashboard-query-complexity.mjs, scripts/prune-dashboard.mjs Repository-local analysis of authored Dashboard Language documents, not a second database backend.

This table groups commands by responsibility, not by interchangeable executables. Inspect the executable trees with gh cao --help, gh cao --help, and cao-dashboard --help; use native subcommand help to inspect each registered child and its flags. help is built-in discovery, not another operation. pages remains dashboard-page discovery in both the operator and Node runtimes.

cao-dashboard owns server hosting and administration, including serve, serve-hosted, serve-pages, azure-functions, ingest, collect, backfill, execute-cli, hosted-cli queue, database, admission validate, audit, doctor, app-key-check, compile-queries, benchmark-queries, otel-smoke, simulate-api, and simulate-webhooks. Its read-only doctor checks server state, data, queries, and collection; it is distinct from the operator installation doctor. File-database repair commands are removed. See the server reference for deployment and administration contracts.

Other server binaries are separate process boundaries, not gh cao subcommands: cao-webhook-gateway selects isolated receive, dispatch, local, or discover roles; cao-cli-quota consumes an internal stdin/stdout scheduling protocol; and cao-cli-relay wraps a hosted workload inside its network-isolated container. The npm cao bin and npm run dashboard:data -- <command> invoke the same Node entry point, not additional command registrations. npm dashboard serving scripts wrap cao-dashboard; they do not move server operations into Node.

The extension is entirely Go and does not execute Node.js, npm, or installed JavaScript modules. Its default reviewed dashboard catalog, canonical source projections, and MCP contract are embedded from the same JSON documents used by the dashboard. pages, queries, query-info, and definition-only prompt work outside an installed control repository. Use --dashboard FILE to read an explicit dashboard document and its directory-confined fragments.

Evidence queries use a consistent PostgreSQL read session through the bundled Go server. They do not bootstrap schemas, migrate storage or repair files. Acquire verified canonical JSONL with gh cao download --url URL or an authenticated Actions artifact, then ingest into the selected PostgreSQL namespace. gh cao dashboard manages its own local database by default. Policy mutations still operate on the current control checkout; the executable does not grant rollout authority.

gh cao setup
gh cao setup --repository 'my-monalisa-org/*'
gh cao setup auth github-app --help
gh cao setup auth enterprise-app --help
gh cao setup auth hosted-cli --help
gh cao setup auth token --help
gh cao add daily-repo-status
gh cao add githubnext/gh-cao/dependabot
gh cao repos add acme/example-service
gh cao campaigns mode preview dependabot
gh cao campaigns enable dependabot
gh cao campaigns disable dependabot
gh cao doctor --json
gh cao pages --json
gh cao query campaign-runs --param campaign=dependabot

All help works offline, including gh cao setup --help and gh cao campaigns --help. Campaign mode and enablement controls are available under campaigns. Workflow and campaign installation use gh cao add. Repository enrollment uses gh cao repos add OWNER/REPO; root-level add installs standalone workflows or campaign packages, not repositories. Authentication is grouped under gh cao setup auth; there is no root-level gh cao setup-auth command. Run gh cao setup without a subcommand for guided control-plane setup, or configure credentials independently with gh cao setup auth github-app, gh cao setup auth enterprise-app, or gh cao setup auth token. Each authentication profile retains its existing options, dry-run behavior, credential prompts, and separate read/write scope. New github-app installations on github.com preselect the read App's control repository plus exact allowlist, and the write App's control repository or explicit --write-repository replacement scope. Review and approve the preselected repositories on GitHub. Existing installations retain Configure; GHES/data-residency hosts retain manual selection. Missing/invalid IDs, failed lookups, or more than 100 repositories stop preselection without widening or truncating access; see limits and recovery. Installation coverage is still verified, --dry-run --repo OWNER/REPO stays offline, and --no-open prints browser URLs. After wildcard expansion, guided setup skips authentication prompts when every remote target is confirmed public, using Actions' built-in token for public-only monitoring. The control repository itself may be private or internal: its own job token can read it without an App or PAT. Fresh setup leaves the authentication mode unset and stores no credentials. An existing conflicting repository or inherited organization mode receives an explicit workflow-token override. Review still requires confirmation; setup has no Pages publication step. Nonpublic remote targets or unknown visibility never qualify; lookup failures stop setup. For authenticated operations, use gh cao setup auth. Its unattended monitoring shortcut is to repeat --repository OWNER/REPO or pass a quoted OWNER/* to snapshot currently public repositories. This public monitoring quickstart does not publish evidence to Pages; exact private/internal remote inputs fail. It enables no agent execution or campaigns. Review and publish the resulting exact policy. Public evidence is marked partial when logs/artifacts or authenticated enrichments cannot be guaranteed; it is not reported as complete zero activity. The dedicated hosted-executor App profile also runs natively, without a Node runtime or installed control checkout:

gh cao setup auth hosted-cli --repo OWNER/CONTROL \
  --target-repository OWNER/TARGET --private-key-out /secure/bootstrap.pem

It creates a separate private App with exactly actions, contents, pull requests, and workflows write plus metadata read. Targets are explicit same-owner repositories, never inferred from policy. GitHub's browser flow requires creation and installation approval with Only select repositories. New github.com installations preselect only the control repository for review; repository-admin additions to an approved installation retain their browser fallback when denied. --app-name, repeatable --target-repository, --no-open, and --dry-run are supported. Dry-run prints the manifest, targets, and executor environment names without contacting GitHub or requiring a key destination.

The private key is written to a new mode-0600 temporary bootstrap file, never overwritten or printed. Import it into the execute-cli deployment's secret manager, then securely remove the file. A failed post-creation verification keeps the downloaded key for recovery but does not print success configuration. Keep it separate from dashboard login and Actions read/write credentials. Setup does not change policy, Actions secrets, authentication mode, or enable hosted execution. The retired Node profile fails before any side effects and directs operators to gh cao setup auth hosted-cli; it does not wrap Go. The native JSON result for authentication retains command: "setup-auth". gh cao setup auth token --help also works offline. Campaign installation through add and package updates through update retain gh-aw option passthrough. JSON output, repeatable query parameters, stdin queries, interactive secret prompts, and command exit codes retain their existing contracts. There is no gh cao run: workflow execution still belongs to gh-aw.

gh cao add WORKFLOW_OR_CAMPAIGN

gh cao add is the single native command for installing a standalone CAO workflow or a campaign package. There is no campaign-installation subcommand. Both installation kinds use gh-aw; CAO verifies and registers standalone workflows or materializes and merges declared campaign workers without widening policy.

Operation Command
Install one standalone workflow gh cao add WORKFLOW [--force] [--engine ENGINE]
Install a campaign package gh cao add CAMPAIGN [GH_AW_ADD_OPTIONS...]
Enroll one exact repository gh cao repos add OWNER/REPO 
gh cao add daily-repo-status
gh cao add daily-repo-status@FULL_COMMIT_SHA
gh cao add githubnext/gh-cao/.github/workflows/daily-repo-status.md@main
gh cao add https://github.com/githubnext/gh-cao/blob/main/.github/workflows/daily-repo-status.md
gh cao add ./my-report.md --force
gh cao add githubnext/gh-cao/dependabot@FULL_COMMIT_SHA
gh cao add ./dependabot --force

Bare catalog workflow names resolve to CAO's .github/workflows/ directory, not gh-aw's implicit workflows/ directory. The published githubnext/gh-cao/daily-repo-status and repo-status shorthands remain workflow sources. Explicit .md sources and GitHub blob URLs also select workflow installation. Campaigns use OWNER/REPO[/PATH][@REF] coordinates or existing local directories; trailing options are passed unchanged to gh-aw. Missing explicit local directories fail rather than resolving remotely. Standalone workflows accept only --force and --engine; custom install directories, renames and gh-aw publication flags are not accepted because the source must retain its exact standalone CAO identity.

After gh-aw succeeds, CAO verifies the installed standalone import and compiled lock, then atomically registers the workflow in control-plane.workflows. New entries set mode: review, max-mode: review, and max-repositories: 1. Existing entries (including disables and live settings), defaults, campaign policy and scope are preserved. Missing policy gets the same exact-current- repository baseline as init; prepare the runtime separately with setup. Failed installs do not mutate policy; files left by a partial installation are reported for inspection. Repeating with --force never resets policy.

Interactive standalone workflow additions offer commit/push of only the installation changes using the same review safeguards as setup. Pre-existing edits to an installation file, a staged index, a non-default branch or unsynchronized remote block automated publication. Unrelated work is never staged. After successful publication, a separate default-No confirmation can request a first review run through gh aw run on the published default branch, with target/required inputs and explicit-scope checks. CAO verifies the branch still points at the published commit before dispatch, then checks the returned run's workflow and SHA against that commit. This can spend AI credits and create outputs; CAO admission still applies. Unavailable remote workflows and unknown dispatch outcomes are reported without automatic retries. A branch race or unverifiable run is reported for inspection, not treated as success. Declining, CI/noninteractive use and unchanged repeated additions never cause implicit publication or execution. Run verification needs a GitHub CLI version that returns the native dispatch URL (2.87+). CAO never substitutes gh-aw's latest-run tracking fallback for the activated run's identity; missing identity requires manual inspection, not a retry.

This command requires an extension release containing it; merging source does not update an already installed binary. Review and publish source, lock and policy together. Daily Repo Status explicitly selects gpt-5.3-codex; override it by changing model: in the installed Markdown source and recompiling the lockfile. See the Daily Repo Status quickstart.

Campaign installation fetches only the installed package's full resolvedCommit SHA from the official catalog, or copies only Git-tracked campaign files from a local catalog checkout. It replaces the selected campaign's resources, refreshes its intelligence metadata, and merges declared workers while preserving existing enablement, mode ceilings, campaign settings, and repository scope. It does not reinstall the control-plane runtime or plugin. Missing policy is initialized for the exact current control repository. Campaign installation never commits, pushes or dispatches work. Prepare the root runtime with gh cao setup, not gh cao add; review and commit generated workflows and policy together.

an unsupported file-database repair operation. Neither Activity nor Dashboard Actions is switched to the Go executable.

Publish and refresh workflow value

Run the operational-value skill first. It defines the measurement contract and produces validated *-evidence.jsonl; publishing does not collect evidence, run an evaluator or enable recurring work. Campaign membership is not required: campaign workers and standalone workflows use the same canonical Value display path. Their source stays in the owning repository, while the evaluator, collector and publication machinery may live in the CAO control repository. Daily File Diet, for example, is sourced from github/gh-aw and measured by tooling in githubnext/gh-cao.

Native schema-v2 operational_value envelopes carry compact measurements; richer schema-v2 operational_value_evidence envelopes carry report facts and drilldowns. After either form enters canonical storage through its supported publication path, Dashboard Language selects the latest primary result without workflow-specific dashboard JSON or code.

gh cao value publish github/gh-aw daily-file-diet \
  --server https://dashboard.example.com \
  --input daily-file-diet-pulse-evidence.jsonl

The server must support value publication and already contain the observed repository and workflow. Hosted publication requires an authorized administrator's current, stepped-up OAuth session: supply its cookie value in CAO_SERVER_SESSION and its session-bound CSRF value in CAO_SERVER_CSRF through your private credential environment. These are credentials; never put their values in policy, report files, URLs, commits or shared command history. CAO_SERVER_TOKEN is accepted only for a loopback server with PostgreSQL, not as a remote PAT or hosted authentication fallback.

One original schema-v2 envelope is accepted, up to 8 MiB. The response confirms its identity, original capture time and database revision. Exact retries leave the revision unchanged. Stale captures, changed frozen contracts and rewritten immutable measurements fail rather than replace accepted evidence. Evidence timestamps use UTC and at most microsecond precision; finer nonzero fractions are rejected rather than silently rounded. Activity replacement retains directly published evidence. The synthetic Pages demo and the synthetic Pages demo have no direct-publication endpoint. Pages contains only generated sample evidence, not Activity's operational transport.

Collection is wired automatically by the skill once its frozen function and repository-local recurring collector pass verification. It stages the exact pair with value enable ... --if-absent, preserving existing registrations and explicit disables. Review, commit and deploy those files to publish the reviewed registration; registration does not bypass collection admission. For manual registration or an intentional re-enable, replace COLLECTOR_PATH.mjs with that collector's actual path; an evidence file or renderer is not a collector:

gh cao value enable github/gh-aw daily-file-diet \
  --collector COLLECTOR_PATH.mjs --api-requests 700
gh cao value disable github/gh-aw daily-file-diet

These commands edit local .github/workflows/cao.json; review, commit and deploy that policy and collector together. They do not enable the measured workflow, enroll repositories, upload executable code or immediately start a collection. In particular, a standalone workflow's existence does not cause CAO to discover or schedule its evaluator; recurring collection requires this exact opt-in. --api-requests is required by the reviewed design for a collector that issues GitHub API requests and is omitted for a local-only collector. Activity admits the full ceiling only after ordinary collection and above its protected reserve; missing or insufficient admission publishes the actual deferral reason. Bounded local-only computations run outside its publication path.

When the collector exports definition.acquisition.requirements, value enable normalizes and copies them into the exact reviewed registration. Each requirement freezes a source, quota pool, versioned primitive, selected population scope and cache lifetime. Hosted collection rejects a collector when that manifest no longer matches policy. For one repository collection, multiple workflows declaring the same invocation-cacheable GitHub requirement can reuse byte-identical successful API responses; each workflow still keeps its own request ceiling, proof and publication checks. The manifest does not grant credentials, repository scope or additional quota. A failed refresh retains the last accepted capture without changing its timestamp or inventing a zero. Disable stops future collection, not history. An explicit disable persists even if the skill is used again. See the collector contract.

Diagnose the installation

Run gh cao doctor from the control repository root, or use gh cao doctor --json for machine-readable results. No Node.js runtime is required. Checks cover:

  • The GitHub CLI executable and installed gh-aw version.
  • Authentication reported by gh auth status, which may contact GitHub.
  • The local .github/workflows/cao.json file's basic structure and exact gh-aw-version pin, including agreement with the installed compiler.

Text output labels each check PASS, FAIL, or SKIP and provides remediation for failures. JSON output contains command, ok, and checks; each check has name, status, message, and optional remediation. Results are still emitted when checks fail; the command exits nonzero on any failed or skipped check. External checks have a 15-second timeout (the local GitHub CLI version probe has a shorter five-second limit). Cancellation stops the diagnostic.

The command is read-only: it does not install extensions, log in, modify policy, repair databases, or change remote settings. Raw authentication output and subprocess errors are not included in reports. A passing basic policy check does not establish rollout authority or full schema validity; use the CAO validation workflow for full policy and workflow validation.

CAO and gh-aw have separate jobs:

  • gh cao configures CAO policy, authentication, installed campaigns, workflow enablement, and queries evidence.
  • gh aw run starts a compiled agentic workflow.
  • gh run lists, watches, and inspects the resulting GitHub Actions runs.

Common Operator Loop

# Add a campaign and merge its workers into CAO policy.
gh cao add githubnext/gh-cao/dependabot

# Keep the campaign review-only and enable its workflows.
gh cao campaigns mode preview dependabot
gh cao campaigns enable dependabot

# Review and commit the workflow and policy changes together.
git diff -- .github
git add .github
git commit -m "Configure Dependabot campaign"
git push

# Run one bounded review.
gh aw run dependabot --ref main \
  --raw-field target_repo="acme/example-service" \
  --raw-field max_repos="1" \
  --raw-field rollout_percent="100" \
  --raw-field safe_output_mode="review"

gh cao campaigns mode preview writes mode: review to .github/workflows/cao.json. The word preview distinguishes this operator command from a live promotion; campaign execution still reports review mode.

Configure the Control Plane

Command Use it to
gh cao setup Prepare missing bare runtime and baseline policy, then guide scope and authentication without configuring Pages. No prior init is required.
gh cao setup linear|jira|ado ... [--json] [--dry-run] Prepare secret-free external-source enrollment and service-specific webhook instructions; does not deploy or activate the receiver.
gh cao init Optionally create only a local minimal review-safe policy for scripting. No runtime installation or remote configuration; refuses existing policy.
gh cao setup admission --repo OWNER/REPO --url HTTPS_URL [--dry-run] Configure non-secret admission variables (OIDC requires no workflow secret); --dry-run previews changes.
gh cao admission status --repo OWNER/REPO [--json] Read effective admission settings, including repository overrides of inherited organization variables.
gh cao admission disable --repo OWNER/REPO [--dry-run] Disable the cooperative gate by setting an empty repository URL, without deleting the override and reactivating organization defaults; --dry-run previews changes.
gh cao setup admission --all-repos --url HTTPS_URL [--dry-run] Configure all repositories selected by the current control repository's validated global CAO scope.
gh cao setup admission --org ORG [--org ORG...] --url HTTPS_URL [--dry-run] Configure organization defaults with visibility all, including future repositories; preserve repository overrides.
gh cao setup admission --enterprise SLUG --url HTTPS_URL [--dry-run] Enumerate enterprise organizations and configure their organization variables, with enterprise read and per-organization Variables write access.
gh cao setup auth github-app ... Configure organization-owned read and write Apps.
gh cao setup auth enterprise-app ... Configure existing enterprise-owned Apps with policy-derived read scope and explicit --write-repository output scope.
gh cao setup auth hosted-cli ... Create the dedicated least-privilege App that the dashboard server's optional execute-cli worker uses for single-use, repository-scoped command tokens.
gh cao setup auth token ... Configure explicitly consented owner-scoped fine-grained PAT pairs when an App is unavailable.
gh cao add OWNER/REPO/CAMPAIGN Install one campaign and merge its declared workers into policy without broadening rollout or enabling live mode.
gh cao repos add OWNER/REPO Verify GitHub CLI read access and stage one exact repository in local control-plane policy, with review-mode overrides for existing campaigns.
gh cao deploy azure --plan --config FILE --out FILE Review a fresh Azure Functions deployment using the embedded template without writing to Azure; --apply --plan-file FILE then repeats preflight and refuses topology and change-set drift. See Azure deployment.
gh cao update Upgrade gh-aw when required, update installed campaigns, and refresh worker declarations while preserving operator-owned settings.
gh cao update --campaign SLUG Update exactly one installed campaign, retaining runtime materialization and worker-declaration refresh. Use root for the CAO root package.
gh cao upgrade-gh-aw VERSION Install an exact gh-aw release, upgrade local Agentic Workflow files, and update the pinned policy version after the upgrade succeeds.

Update and enrollment details

Omit --campaign to update all installed CAO packages. Selection also works with refs and update options, for example gh cao update main --campaign dependabot. The slug is the last component of the installed package name (root for githubnext/gh-cao). Unknown, ambiguous, empty, unsafe, or repeated selections fail before updates or gh-aw upgrades. Campaign selection does not narrow a required gh-aw compiler upgrade, which may refresh shared workflow files.

The canvas Updates page exposes Add repository beside Repositories. Its debounced GitHub search only selects a target; execution still requires fresh approval of the exact gh cao repos add OWNER/REPO command. Enrollment requires existing exact owner and repository allowlists and does not rewrite a broad discovery policy. An already enrolled repository is unchanged. New targets stay in review mode even when a campaign defaults to live. The command neither commits nor pushes, enables campaigns, changes rollout limits, configures credentials, nor expands an explicitly narrowed Activity scope. Review and commit the policy before activation at a reviewed workflow SHA.

Repository enrollment runs entirely in the Go extension and does not require Node.js or installed Activity runtime files.

Setup and manual campaign execution

Use gh cao setup for review-before-apply configuration and optional separately approved publication. Setup installs no campaign or agentic execution; a push starts normal monitoring Actions asynchronously. To add automation afterward, follow the manual Repo Assist walkthrough using gh cao add and gh aw run.

Without an interactive terminal or when CI is set, gh cao setup applies only the agent-safe public profile: exact current-repository read and Activity scope, no campaigns, no Pages configuration, and repository GITHUB_TOKEN (workflow-token) authentication. It refuses private/internal control repositories, broader existing policy, or installed campaigns. gh cao setup --json returns the applied profile with "nonInteractive": true. Bare installation remains usable before setup with exact control-repository scope, no operational campaigns, and repository-local workflow-token Activity access.

Control Campaigns

# Map the campaign to review mode in policy.
gh cao campaigns mode preview dependabot

# Promote only after review and explicit approval.
gh cao campaigns mode live dependabot

# Enable or disable every installed workflow declared by the campaign.
gh cao campaigns enable dependabot
gh cao campaigns disable dependabot

These commands accept multiple campaign slugs:

gh cao campaigns disable dependabot repo-assist

mode live does not widen repository scope, grant target consent, or create credential access. Complete the live rollout gates separately. It also checks whether the control repository has a selected GitHub App or PAT with write credentials configured. If CI can confirm they are missing, it suggests gh cao setup; lack of permission to inspect Actions settings does not block the mode change. This check does not verify installation access or token permissions.

disable prevents new starts for the campaign's installed workflows. It does not cancel an active run or replace the control-plane emergency stop.

Validate the Control Plane

Control-plane validation is Actions-only. Publish reviewed configuration changes to the control repository's default branch and inspect CAO validation in Actions. To request another validation run:

gh workflow run cao-validate.yml
gh run list --workflow cao-validate.yml --limit 5

Validation checks the policy with the production resolver, the installed gh-aw compiler version, strict compilation and generated workflow drift, campaign workflow identity and enablement, gh aw doctor, and bounded trust-boundary security rules. GitHub workflow state is reported as unknown when API access is unavailable. Warnings do not fail the workflow by default.

JavaScript runtime at the installed revision. This is the sole implementation; gh cao does not expose validate. CI does not build or download the Go extension or require consumer npm metadata. The internal runtime command retains --strict-warnings for Actions callers that require warnings to fail.

Strict compilation runs against a committed temporary snapshot of the current workflow files in the Actions checkout, without rewriting generated artifacts. A monitoring-only installation with no top-level .github/workflows/*.md sources skips compilation, but still checks for orphaned .lock.yml artifacts and runs the other validation checks above. Existing Markdown sources always undergo strict compilation, even when their frontmatter is missing or malformed.

CI writes its JSON report under RUNNER_TEMP, outside the checkout, before uploading the cao-validation artifact. This keeps report creation from triggering a false gh aw doctor warning and validation issue on a fresh installation. Download the structured report with gh run download RUN_ID --name cao-validation.

Exit code 0 means no validation errors, 1 means validation findings failed the requested threshold, and 2 means the validator itself could not complete. Validation never rewrites workflow artifacts; run npm run compile:locks to regenerate stale locks.

Run and Watch a Campaign

There is intentionally no cao run command. gh-aw owns workflow execution:

gh aw run CAMPAIGN --ref BRANCH \
  --raw-field target_repo="OWNER/REPOSITORY" \
  --raw-field max_repos="1" \
  --raw-field rollout_percent="100" \
  --raw-field safe_output_mode="review"

The legacy Activity and dashboard artifact workflows are removed. Operational analysis uses an explicitly prepared snapshot or the authenticated hosted service.

Then use GitHub CLI to find and watch the orchestrator:

gh run list --workflow CAMPAIGN.lock.yml --event workflow_dispatch --limit 5
gh run watch RUN_ID --exit-status

Manual inputs may narrow checked-in policy for one run; they never widen it.

Operate the Hosted CLI Backend

The server binary includes a privileged operator interface for the hosted CLI queue. Run it in the trusted executor environment with the same operational store configuration as execute-cli:

cao-dashboard hosted-cli queue list --status queued --limit 50
cao-dashboard hosted-cli queue list --status queued --limit 50 \
  --continuation-token TOKEN_FROM_PREVIOUS_PAGE
cao-dashboard hosted-cli queue show COMMAND_ID
cao-dashboard hosted-cli queue cancel COMMAND_ID --actor OPERATOR_LOGIN

Queue output contains command summaries, not invocation values or process output. List responses include limit, hasMore, and, when another page is available, nextContinuationToken. Pass that opaque token to --continuation-token with the same status filters to retrieve the next page. The cursor follows command IDs and does not count or skip preceding rows. Cancellation is an operator override that bypasses the dashboard requester's live repository-permission check; it requires a durable audit store and records the supplied operator login as a self-reported identity, not proof of the caller's identity. Restrict database and executor environment access accordingly. See Hosted CLI actions for the operator workflow and local development limitation.

For a single-worker development loop without a dispatcher, use Local Worker Debugging. Its request-only debug mode is not a gh cao campaigns mode command or a campaign configuration.

CLI failures print one actionable message by default. Set CAO_DEBUG=1 only when diagnosing the CLI itself and an internal stack trace is needed.

Inspect Activity

First download a successful Activity run's bounded operational artifact with authenticated Actions read access:

gh run download RUN_ID --repo OWNER/CONTROL --name cao-activity-index --dir .cao

This supplies normalized canonical JSONL for explicit PostgreSQL ingestion. Production and local dashboards share the Go/PostgreSQL query boundary:

npm run dashboard:local -- --source ../.cao --postgres-url "$CAO_POSTGRES_URL"

The npm command runs from a catalog checkout; relative Go paths resolve from server/. Existing caches serve offline without another download.

Alternatively, if an operator already provides a trusted operational payload location, select its manifest:

gh cao download --url https://evidence.example/operational/payload-hashes.json

This illustrative URL is not a CAO hosted export endpoint. Native and JavaScript download commands require --url or DASHBOARD_DATA_URL ending in /payload-hashes.json. There is no implicit Pages source or site-directory discovery. Local Go serving likewise needs an explicit operational source when its cache is absent or refresh is requested. Synthetic manifests and manifests without canonical shard and inventory checksums are rejected.

Pages is only a generated synthetic enterprise demo. It exports neither SQLite nor an operational agent summary and must not be used for operational analysis. The download remains local under .cao/; it is evidence, not rollout authority. Use a trusted HTTPS source; redirects cannot downgrade HTTPS to HTTP. For independent manifest integrity, pass --manifest-sha256 SHA256 (or set DASHBOARD_MANIFEST_SHA256) with a digest obtained through a separate trusted channel. Checksums fetched alongside the snapshot detect corruption, not a compromised publisher or TLS trust authority.

Use the gh-like query surface for common questions:

gh cao gh runs --repo OWNER/REPOSITORY --status failure --limit 20
gh cao gh issues --repo OWNER/REPOSITORY --since 2026-09-01
gh cao gh prs --repo OWNER/REPOSITORY --workflow WORKFLOW --limit 10

Check runtime health or query canonical records:

gh cao computation intelligence
gh cao computation intelligence --campaign dependabot --previous prior-intelligence.json --feedback decision-feedback.json
gh cao computation runtime-health --campaign dependabot
gh cao computation runtime-health --campaign dependabot --diagnose

gh cao query \
  --collection runs \
  --where conclusion=failure \
  --limit 20

For the computation model and result semantics, see Intelligence, Runtime Health Computation, and Portfolio Intelligence Computation.

The intelligence computation fingerprints canonical runtime-health evidence, correlates matching failure signals, suppresses ineligible or recovering candidates, and emits advisory Decisions. It never dispatches workers or grants execution authority. Passing a prior result with --previous reuses unchanged nonterminal Decisions. A versioned --feedback file binds dispositions to a Decision ID and input fingerprint; unchanged terminal Decisions are suppressed, while stale feedback remains inspectable and cannot affect changed evidence.

The result also includes partial Campaign intelligence contracts compiled from declared canonical inventory. Undeclared problem, outcome, schedule, overlap, attention, and operational-value fields remain null; descriptions and READMEs are not reinterpreted as those contracts.

Feedback uses this shape:

{
  "contractVersion": "1.0.0",
  "records": [{
    "decisionId": "runtime-health-decision:...",
    "inputFingerprint": "sha256:...",
    "disposition": "deferred",
    "observedAt": "2026-10-01T11:00:00Z",
    "actor": "operator:octocat",
    "authority": "control-repository-review"
  }]
}

Allowed dispositions are accepted, rejected, deferred, superseded, recovered, expired, and unresolved. Feedback never grants execution authority.

Render a named dashboard query as an editable agent prompt with the same template as the UI:

gh cao prompt cost-by-campaign
gh cao prompt campaign-runs --param campaign=dependabot --postgres-url "$CAO_POSTGRES_URL"

Without an explicit PostgreSQL connection, definition-only prompts need no database and include no evidence rows. With --postgres-url, the command can include a bounded preview from that provisioned namespace; this does not grant rollout authority. Use --dashboard FILE to experiment with a different dashboard definition.

There is no file-database repair, backup conversion or compatibility command. PostgreSQL retention and partition maintenance remain explicit schema-owner operations through cao-dashboard database maintain --store canonical --namespace NAME. Native gh cao doctor and cao-dashboard doctor remain read-only diagnostics. They are different from gh aw doctor, which validates workflow installation and repository setup.

Evaluate and Evolve

The CLI also exposes evidence used to improve campaigns:

Command Purpose
gh cao api-cost --profile daily-file-diet Estimate GitHub quota, collector-grant, and runner bottlenecks from retained canonical Daily File Diet evidence.
gh cao api-cost --profile daily-file-diet --server URL --calibrate Calibrate the Daily File Diet model from hosted PostgreSQL request-pool and wall-time observations.
gh cao api-cost --input SCENARIO.json Simulate another declarative data-acquisition request profile.

Without --database, dashboard-complexity normalizes every canonical database table to weight one. With --database FILE, it weights tables by their deployed row counts (normalized to the largest table) read from that downloaded snapshot, giving a more realistic computation-pressure ranking.

api-cost is a planning model, not admission. It reports sustained and peak core, Search, and GraphQL demand; the modeled and full-grant-guaranteed fleet limits; and serialized runner capacity. The built-in Daily File Diet retained scenario queries the canonical operational-value-evidence source from the local PostgreSQL namespace, or from hosted PostgreSQL through --server URL. It has no checked-in evidence-file or hard-coded population fallback; missing database evidence is unavailable. Use CAO_SERVER_TOKEN for a loopback server, or the same CAO_SERVER_SESSION and CAO_SERVER_CSRF administrator session values as hosted Value publication. --scenario hard-bound tests the collector's declared pagination and population ceilings without requiring retained data. --calibrate requires --server; it uses bounded private daily cost aggregates from the last 30 days across the hosted Daily File Diet fleet and fails when none exist. PostgreSQL reduces detailed repository accounting to a bounded workflow-level series before Dashboard Language aggregates it. Observed costs affect modeled capacity, while guaranteed capacity continues to reserve the collector's full reviewed request grant. Use --collection-window-hours to compare one synchronized hourly batch with a webhook- or queue-spread collection window. See the GitHub API Capacity Specification.

Data-pipeline and dashboard-maintainer commands are listed by gh cao --help. For the full data workflow, see Dashboard data ingestion.

Review What Each Command Changed

init, add, update, upgrade-gh-aw, and campaigns mode can change checked-in control-plane files. Review those changes and commit workflow sources, generated locks, and .github/workflows/cao.json together:

git status --short
git diff -- .github

Never edit generated .github/workflows/*.lock.yml files by hand. Never treat a successful command as permission to widen scope or enable live output.