# Wheelie CLI support map

Agent docs index: /llms.txt

This page is a launch-boundary map, not exhaustive help. Run top-level help and family-specific help in the installed CLI for current command syntax. Use [Command taxonomy](./command-taxonomy.md) for the public-safe distinction between `app`, `instant`, `agent`, `agent-run`, and `models`. The public growth path is intentionally small: use an existing checkout or public GitHub repo, bring a harness you already use when clean stable reports `requires_adapter`, produce one reviewable diff, and run focused validation evidence before relying on submit/watch/checkpoint. The installed `wheelie` CLI is the preferred automation surface for coding agents, local harnesses, scripts, source/candidate/change operations, validation, submit, and watch; Wheelie over SSH is the zero-install human onboarding/demo/recovery path plus a constrained read/status fallback. JSON and NDJSON outputs should include typed `support_state`, `reason`, and `next_action` fields when the command needs auth, grants, adapters, capacity, or a supported project catalog. For launch support triage, use [Support and friendly error states](./support.md).

## Launch command taxonomy

Top-level help is organized by the job a launch user is trying to do, not by internal adapter maturity. Each public family should advertise one support state and one next action in human help and JSON receipts:

| Category | Families | Launch wording |
| --- | --- | --- |
| Getting started, auth, and model credentials | `version`, `doctor`, `update`, `auth`, `agent-grant`, `models`, `completions`, `feature-discovery` | Establish the signed CLI trust root, sign in without raw tokens, and label BYOK/subscription/managed/enterprise model-provider support before any run uses credentials. |
| Running work, sessions, and agent runs | `work`, `working-copy`, `start`, `message`, `logs`, `agent`, `coding`, `agent-run`, `chat`, `questions` | Anchor one task to a working copy or session. `message` is mid-task intervention/follow-up input. Local, VM-backed, and hosted sessions should be labeled by returned support state rather than described as Ghostty-only. |
| Source, change control, validation, and evidence | `source`, `change`, `submit`, `watch`, `why`, `validation`, `evidence`, `proof`, `checkpoint`, `context` | Treat `change` as the high-level workflow/change-control abstraction over source snapshots, review adapters, checks, submit/watch, and evidence—not as raw `git diff`. |
| Infrastructure, resources, previews, and operations | `vm`, `run`, `resources`, `capacity`, `instant`, `app`, `preview`, `deps`, `stack`, `daemon`, `operation`, `wait`, `release` | Distinguish prompt-to-HTTP hosted preview (`instant`) from packaged app publication/lifecycle (`app`). Label managed VM/run/capacity support as live readback, preview, allowlist, or adapter-gated. |
| Integrations, discovery, governance, and advanced surfaces | `integration`, `github`, `notify`, `orchestrator`, `attention`, `opportunities`, `harness`, `package`, `pi`, `projection`, `schema`, `artifacts`, `capability`, `analytics`, `tool`, `audit`, `branding` | Explain provider integration boundaries without implying raw provider CLI authority. Unsupported or future surfaces should be hidden or return typed `unsupported` / `requires_adapter` receipts with a safe next action. |

## Launch-preview command path

Rows in this table are command families in the first-run flow, not blanket green live claims. `allowlist`, `requires_adapter`, `optional_adapter_absent`, and `preview` responses are truthful supported outcomes and should stop an agent before it assumes live effects.

| Family | Example | Support level |
| --- | --- | --- |
| install | `curl -fsSL https://get.wheelie.dev | sh` | native |
| version | `wheelie version --json` | native |
| update | `wheelie update --dry-run --json` | native |
| doctor | `wheelie doctor --json` | native |
| auth | `wheelie auth login` / `wheelie auth status --json` | native command; browser/device auth may return `allowlist` during launch preview |
| models | `wheelie models list --credential-mode subscription --json` | public command; clean stable bootstrap may report `requires_adapter` until a model/project adapter is attached; BYOK support must label mediated, short-lived, or raw env/file projection mode |
| integration | `wheelie integration connect github --repo octocat/Hello-World --json` | native command; public sample-repo connection may return `allowlist` during launch preview |
| source materialization | `wheelie source status --repo octocat/Hello-World --json` | native for documented public GitHub repos; private/non-public GitHub repos are launch-deferred until the mediated source-provider adapter/allowlist path is attached for the selected repo; see [private/non-public GitHub repositories](./private-repos.md) |
| harness | `wheelie harness install pi --dry-run --json`; `wheelie harness status pi --json` | clean public stable reports `requires_adapter` until a richer Wheelie package or project adapter provides the projection installer/status implementation; Claude/Codex are projection/BYO harness paths; Flue is deferred and has no public launch install path |
| context | `wheelie context pack --purpose coding --level startup --json` | native bounded context; may be partial without auth/grants |
| work | `wheelie work create --title "Update the README greeting" --json` | native local/hosted WorkGraph contract; clean profiles do not require external tracker/provider tokens |
| work handoff | `wheelie work open-working-copy wheelie://work-items/<id> --repo <org>/<repo> --launch pi --json` | public command; live materialization needs source adapter and may be allowlist-gated; clean bootstrap treats `--launch pi` as working-copy handoff only and returns `requires_adapter` unless a non-null agent session/projection receipt is emitted; BYO harness from an existing checkout remains the honest one-afternoon fallback |
| work status/watch | `wheelie work status wheelie://work-items/<id> --json`; `wheelie work watch wheelie://work-items/<id> --cursor <token> --limit 100 --ndjson` | stable public commands for task readback and bounded events. Session/terminal attach is preview adapter work until `wheelie work --help` lists session subcommands; use status/watch as the safe next action. |
| Wheelie over SSH | `ssh wheelie.dev`; `ssh wheelie.dev work get wheelie://work-items/<id> --json`; `ssh wheelie.dev work watch wheelie://work-items/<id> --ndjson --max-wait-secs 120` | launch-preview zero-install human entrypoint; auth pairing, imported-key binding, command mode, and TUI mode require verified account/session-broker support and may return `allowlist`, `requires_auth`, `requires_adapter`, or `unsupported`; agents and scripts should prefer the installed CLI and use SSH command mode only for quick read/status checks or constrained environments; see [Wheelie over SSH](./ssh.md) |
| managed VM SSH / terminal control | `wheelie vm status <name-or-id> --json`; `wheelie vm ssh <name-or-id> --json` | advanced preview/control path; requires a named managed workspace plus auth/capacity/session-broker support and may return `requires_adapter`, `allowlist`, or `capacity_limited` |
| working-copy | `wheelie working-copy status <name-or-id> --json` | native command; live source access may require adapter |
| validation | `wheelie validation plan --json` | native local Git validation lane only inside a materialized checkout; clean non-checkout environments and richer lanes need a project validation catalog/adapter |
| change | `wheelie change status --change <change-id> --json` | public command; live progress needs change adapter |
| release | `wheelie release status --sha <candidate> --json`; `wheelie release wait --sha <candidate> --match effective_inclusion --max-wait-secs 60 --json` | public command; live data needs a project release-readback adapter. Default status/wait semantics are effective inclusion (`effectiveIncludesTarget` true for exact live commit, live descendant, or authorized provider-artifact readback); use `--match exact` only when exact release identity matters. |
| wait | `wheelie wait status --subject <ref> --goal <goal> --json`; `wheelie wait guard --subject <ref> --goal <goal> --max-wall 15m --json` | native generic convergence guard. App adapters emit `wheelie_wait_observation/v1`; Wheelie writes `wheelie_wait_decision/v1` receipts for success, handoff, supersession, no-progress, candidate-fault, and escalation outcomes. |
| submit | `wheelie submit --change <change-id> --dry-run --json` then explicit `--apply` only after preview acceptance | public command; default is admission preview, live submit needs explicit apply plus change adapter and evidence |
| watch | `wheelie watch --change <change-id> --cursor <token> --max-wait-secs 900 --ndjson` | public command; live events need change adapter |
| agent-run API | `wheelie agent-run create --request-json <path\|-> --idempotency-key <key> --json` | preview command; hosted agent-run create/continue/watch/export requires an Agent Run service adapter, scoped auth, idempotency keys for mutations, and budget/readiness receipts when model spend may occur |
| Wheelie Instant | `wheelie instant status <app-ref> --json`; `wheelie instant run --prompt "make a tiny status page" --env hosted --json` | local fixture status/preview is no-live; hosted instant run/start is adapter-gated and must return `requires_adapter` until a hosted-preview adapter reports support |
| checkpoint | `wheelie checkpoint create --message "ready for handoff" --work-item wheelie://work-items/<id> --context-file handoff.md --json` | public command; clean package projection may report preview until a checkpoint store is attached |
| resources | `wheelie resources status --json` | native for local read-only host posture plus launch-safe managed quota/provider quota/usage-metering policy summaries; authenticated managed-VM, validation-executor, and usage-metering readbacks populate when available, while unauthenticated or unsupported accounts return typed nested readback states. This is not live billing or payment support: `money_movement_enabled=false` unless a separate approved support receipt exists. |
| cleanup | `wheelie working-copy delete <name-or-id> --dry-run|--apply --json`; `wheelie working-copy gc --dry-run --json` | native for single clean registered working-copy delete with typed receipt; broad GC apply still requires the full working-copy/source cleanup adapter |
| feature discovery | `wheelie feature-discovery status --json` | native low-noise hints; shared catalog/schema at `/services/wheelie/feature-discovery.json` and `/schemas/wheelie/feature-discovery.openapi.json` |

## Visible non-MVP families

| Family | Support level | Public guidance |
| --- | --- | --- |
| agent packages | preview | Use only when the command reports the needed adapter as available. Community packages/examples/demos must follow the [contribution policy](./community-contributions.md): descriptor-first review, trust labels, dry-run receipts, and no unsupported public claims. |
| Wheelie Instant | preview / requires_adapter | Use `wheelie instant run` only when the command reports an authenticated hosted-preview adapter. Clean native Wheelie only reads local no-live fixture status/preview. Keep fixture/demo, private hosted preview, and generally available support labels distinct; receipts must redact capability URLs and secrets. |
| agent-run API | preview / requires_adapter | Not a first-run native path; hosted create/continue/watch/export operations require an Agent Run service adapter, scoped auth, and idempotency keys for mutations. |
| browser-assisted sessions | preview | Do not assume autonomous browser access without an explicit capability. |
| Wheelie over SSH | preview / allowlist | Use `ssh wheelie.dev` for zero-install human onboarding/demo/recovery and `ssh wheelie.dev <command>` for bounded JSON/NDJSON read/status checks only after pairing succeeds. Prefer the installed `wheelie` CLI for agent automation, local harnesses, source/candidate/change operations, validation, submit, and watch. Raw shells, raw provider/admin commands, secret-pasting, and parallel agent-control protocols are unsupported. |
| managed VM SSH / terminal control | preview | Use only after `wheelie vm status` names a managed workspace and `wheelie vm ssh` returns a typed non-adapter session receipt; raw terminal text is not lifecycle authority. |
| web context demos | unsupported / fixture-only | Not part of the public coding MVP; do not claim live web freshness, provider access, or public pricing from sample demos. |
| Slack notifications | preview | Notifications are not required for first run. No named live Slack app/workspace/channel install, bot membership, removed-channel, retention, budget-grant, or WorkGraph authority receipt is launch-green. |
| Slack task creation | unsupported | Requires live Slack app/workspace/channel receipts, notification/status backlinks, signed inbound auth, explicit budget grants, and WorkGraph authority before any live claim. |
| A2A cards | preview | Treat as protocol preview unless the project reports support. |
| app hosting | preview / requires_adapter | Not part of the coding MVP quickstart. `wheelie app` is descriptor/fixture/readback in the native bootstrap, not publication or release. |
| platformd capabilities | preview / requires_adapter | Use [`platform-capabilities.md`](./platform-capabilities.md) for public IA and command wording. Probe `wheelie capability list|inspect|test|request`, `wheelie app validate|plan|status`, and `wheelie operation status`; branch on typed support/readiness receipts before claiming hosted support. |
| custom domains | preview | Requires explicit hosting support and ownership checks. |
| capability marketplace | roadmap | Public gallery/readback is visible, but live marketplace install, grants, and invocation need future adapter receipts. |
| generic webhooks and bots | roadmap | Not a launch-live claim until signed inbound auth, tenancy, budget, and cleanup receipts exist. |
| edge or heavy GPU workers | roadmap | Use managed standard workspaces or explicit approved validation executors; do not claim public heavy-worker support. |
| commerce and ticketing | roadmap | Commerce, payouts, refunds/disputes, and ticketing automation are outside the public coding MVP unless a scoped support receipt says otherwise. |
| release status/wait | requires_adapter | Public `wheelie release status/wait` commands expose generic effective-inclusion readback fields; live data needs a project release adapter. |
| wait guard | native | Public `wheelie wait status/guard/handoff` classifies app-neutral wait observations and persists `wheelie_wait_decision/v1` receipts; app-specific live observation providers attach through project adapters. |
| capacity reservations | allowlist | Spendful; continue only after budget/capacity approval. |
| package publication | unsupported | Not part of public coding MVP. |
| additional automation integrations | unsupported | Use supported GitHub connection first. |
| specialized compute workers | unsupported | Use managed standard workspace unless explicitly approved. |
| payment and ticketing workflows | unsupported | Not part of public coding MVP. |

## Agent-readable output requirements

- Prefer the installed `wheelie` CLI over the SSH projection for coding agents, local harnesses, scripts, source/candidate/change operations, validation, submit, and watch.
- Use SSH command mode only for quick read/status checks, demos, recovery, or constrained environments where installing the CLI is not available yet.
- Prefer `--json` for status and mutation results.
- Prefer `--ndjson` for watches and logs.
- Bound output with cursors, limits, paths, and max-wait settings.
- Treat provider URLs, check runs, branch names, local paths, process IDs, and external IDs as metadata.
- Branch on typed fields, not on pretty output.
- Feature discovery must use typed command/workflow/usage fields, respect cooldowns and dismissals, and avoid raw command arguments, source paths, and secrets.
- Stop before spendful work when output reports `allowlist`, `approval_required`, `budget_exceeded`, or `capacity_limited`.
- Do not paste raw provider tokens, cookies, SSH keys, transcripts, source dumps, or secrets into Wheelie commands, SSH sessions, or harness prompts.
- For private/non-public GitHub repos, stop on `source_provider_adapter_required` / `requires_adapter` unless the selected repo returns a mediated source-provider adapter or allowlist receipt; use the [private repo guide](./private-repos.md).
- For saved model/API keys and developer secrets, use the [BYOK and secrets guide](./byok-secrets.md); do not treat raw env/file projection as a claim that agents cannot read the projected secret.