CLI: Operator commands for repos, platform introspection, and day-2 ops

[krokoko]

Component

Scripts / CLI

Describe the feature

Expand the bgagent CLI with operator-focused commands that expose platform state and support day-2 operations without manual AWS CLI / DynamoDB queries or full CDK redeploys.

The CLI today covers task lifecycle (submit, list, status, watch, cancel, nudge, trace), webhooks, Cedar HITL (approve, deny, pending, policies), channel setup (slack, linear, jira), and limited admin (admin invite-user, configure --from-bundle). It does not surface infrastructure or onboarding state that operators routinely need.

Use case

Operators and workshop facilitators are frustrated when they must:

• Run aws dynamodb scan --table-name …RepoTable… to see which repos are onboarded.
• Copy/paste four CloudFormation outputs to configure the CLI (see #17).
• Re-deploy CDK just to confirm stack outputs, store the GitHub PAT, or check whether a secret is populated.
• Dig through the AWS console to find webhook URLs, Cognito pool IDs, or AgentCore runtime status.

A richer CLI reduces time-to-debug and supports the split deploy / runtime onboarding model (companion RFC).

Proposed solution

P0 — Repository & platform introspection

Command	Purpose
bgagent repo list	List onboarded repos from RepoTable (status, model, compute type, updated_at). Requires new GET /v1/repos API or direct DynamoDB read via operator IAM profile.
bgagent repo show <owner/repo>	Full RepoConfig + linked secret ARNs (redacted).
bgagent platform outputs	Print stack outputs (ApiUrl, UserPoolId, AppClientId, GitHubTokenSecretArn, etc.) — wraps aws cloudformation describe-stacks.
bgagent platform doctor	Smoke checks: API reachable, Cognito config valid, default GitHub secret non-empty, Bedrock model accessible, at least one active repo.

P1 — Secrets & identity (reduce raw AWS CLI)

Command	Purpose
bgagent github set-token	Interactive PAT → put-secret-value on stack's GitHubTokenSecretArn (extend existing github set-webhook-secret pattern).
bgagent admin invite-user <email>	Already exists — document as part of setup flow.
bgagent admin create-api-key	If API keys ship — mint scoped keys without Cognito.

P2 — Runtime & deploy (no CDK redeploy)

Command	Purpose
bgagent runtime status	AgentCore runtime version, last update, health (control-plane API).
bgagent repo onboard <owner/repo> …	Runtime onboarding (depends on POST /v1/repos API). Flags: --model, --token-secret-arn, --max-turns.
bgagent repo offboard <owner/repo>	Soft-delete repo config.

P3 — Observability shortcuts

Command	Purpose
bgagent ops stuck-tasks	List tasks in SUBMITTED/HYDRATING/AWAITING_APPROVAL beyond threshold.
bgagent ops concurrency	Per-user active task counts vs limits.
bgagent webhook test <webhook-id>	Send signed sample payload to POST /v1/webhooks/tasks.

UX conventions

• All commands support --output json for scripting.
• Read-only commands (list, show, outputs, doctor) should work with operator AWS credentials (no Cognito) when hitting AWS APIs directly; mutating commands use Cognito or API keys.
• Mirror patterns from bgagent linear webhook-info and bgagent github webhook-info (stack output helpers).

Other information

• Files: cli/src/commands/, cli/src/bin/bgagent.ts, cdk/src/handlers/shared/types.ts + cli/src/types.ts (keep in sync for new APIs).
• Blocked by: GET/POST /v1/repos for full repo CRUD (see split-deploy RFC); P0 platform outputs / doctor / github set-token can ship independently.
• Related: #17 — these commands are building blocks for mise run setup / bgagent setup.
• ROADMAP "Exposed project specifications" — OpenAPI for new endpoints.

Acknowledgements

• I may be able to implement this feature
• This might be a breaking change

[krokoko]

Starting implementation — P1 github set-token with per-blueprint (--repo) support.