cli
cli readiness matrix
Status as of 2026-05-02. Source of truth for registered commands is cli/src/index.ts plus cli/src/commands/**.
Legend:
- ready - command hits a public API route today.
- ready preview - command is registered and calls a preview transport or preview API path.
- local - command only changes local CLI state.
- stub - command is registered and exits 3 with the canonical stub envelope.
- planned - public routes exist, but no
owlettenoun is registered yet. - reference page - linked when a dedicated per-command page exists;
pendingmeans the command is registered but its dedicated page is not created yet.
top-level commands
| command | status | reference page | public route or reason |
|---|---|---|---|
owlette auth login | ready | auth | POST /api/cli/device-code, then POST /api/cli/device-code/poll |
owlette auth status | ready | auth | alias of owlette whoami; GET /api/whoami |
owlette auth logout | local | auth | clears the active profile's stored credential (OS keychain / credentials.json) and any legacy config.toml token; no API call |
owlette whoami | ready | whoami | GET /api/whoami |
owlette version | ready | version | GET /api/version |
owlette rollback <roostId> | ready | rollback | GET /api/roosts/{roostId}, GET /api/roosts/{roostId}/versions/{versionRef}/diff, POST /api/roosts/{roostId}/rollback |
owlette listen | ready preview | pending dedicated page (Task 4.9) | GET /api/events/stream?siteId=<siteId>; scoped SSE liveness transport only until production fanout ships |
owlette trigger <event> | ready | pending dedicated page (Task 4.10) | direct mode posts to the caller's URL; --via-api uses POST /api/webhooks/probe?siteId=<siteId> |
roost
| command | status | reference page | public route or reason |
|---|---|---|---|
owlette roost push <dir> | ready | roost | POST /api/chunks/check, POST /api/chunks/upload-urls, signed PUT, POST /api/roosts/{roostId}/versions |
owlette roost list | ready | roost | GET /api/roosts?siteId=<siteId> |
owlette roost get <roostId> | ready | roost | GET /api/roosts/{roostId}?siteId=<siteId> |
owlette roost diff <roostId> | ready | roost | GET /api/roosts/{roostId}/versions/{versionRef}/diff?siteId=<siteId>&against=<versionRef> |
owlette roost versions <roostId> | ready | roost | GET /api/roosts/{roostId}/versions?siteId=<siteId> |
owlette roost deploy <roostId> | ready | roost | POST /api/roosts/{roostId}/deploy |
site-scoped operator nouns
| command | status | reference page | public route or reason |
|---|---|---|---|
owlette site list | ready | site | GET /api/sites |
owlette site get <siteId> | ready | site | GET /api/sites/{siteId} |
owlette quota show | ready | quota | GET /api/sites/{siteId}/quota |
owlette quota history | ready | quota | GET /api/sites/{siteId}/quota/history?period=<period> |
owlette audit-log list | ready | audit-log | GET /api/sites/{siteId}/audit-log |
owlette audit-log get <recordHash> | ready | audit-log | GET /api/sites/{siteId}/audit-log/{recordHash} |
machine
| command | status | reference page | public route or reason |
|---|---|---|---|
owlette machine list | ready | machine | GET /api/sites/{siteId}/machines |
owlette machine get <machineId> | ready | machine | GET /api/sites/{siteId}/machines/{machineId} |
owlette machine deployments <machineId> | ready | machine | GET /api/sites/{siteId}/machines/{machineId}/deployments |
owlette machine reboot <machineId> | ready | machine | POST /api/sites/{siteId}/machines/{machineId}/commands with type=reboot_machine |
owlette machine shutdown <machineId> | ready | machine | POST /api/sites/{siteId}/machines/{machineId}/commands with type=shutdown_machine |
owlette machine screenshot <machineId> | ready | machine | POST /api/sites/{siteId}/machines/{machineId}/commands with type=capture_screenshot, then GET /api/sites/{siteId}/machines/{machineId}/commands/{commandId} |
owlette machine live-view <machineId> | stub | machine | no public route yet; public-api deferred: swoop |
owlette swoop <machineId> | ready | swoop | GET /api/sites/{siteId}/machines/{machineId}, then the viewer url /swoop/{siteId}/{machineId} |
hoot chat
| command | status | reference page | public route or reason |
|---|---|---|---|
owlette chat new | ready | chat | POST /api/cortex/conversations |
owlette chat list | ready | chat | GET /api/cortex/conversations?siteId=<siteId> |
owlette chat send <conversationId> <message> | ready | chat | POST /api/cortex/conversations/{conversationId} |
owlette chat delete <conversationId> | ready | chat | DELETE /api/cortex/conversations/{conversationId} |
owlette chat rename <conversationId> <title> | ready | chat | PATCH /api/cortex/conversations/{conversationId} |
classic deployments
| command | status | reference page | public route or reason |
|---|---|---|---|
owlette deploy create | ready | deploy | POST /api/sites/{siteId}/deployments |
owlette deploy list | ready | deploy | GET /api/sites/{siteId}/deployments |
owlette deploy get <deploymentId> | ready | deploy | GET /api/sites/{siteId}/deployments/{deploymentId} |
owlette deploy retry <deploymentId> | ready | deploy | POST /api/sites/{siteId}/deployments/{deploymentId}/retry |
owlette deploy cancel <deploymentId> | ready | deploy | POST /api/sites/{siteId}/deployments/{deploymentId}/cancel |
owlette deploy uninstall <deploymentId> | ready | deploy | POST /api/sites/{siteId}/deployments/{deploymentId}/uninstall |
owlette deploy delete <deploymentId> | ready | deploy | DELETE /api/sites/{siteId}/deployments/{deploymentId} |
process
| command | status | reference page | public route or reason |
|---|---|---|---|
owlette process list | ready | process | GET /api/sites/{siteId}/machines/{machineId}/processes |
owlette process get <processId> | ready | process | GET /api/sites/{siteId}/machines/{machineId}/processes/{processId} |
owlette process create | ready | process | POST /api/sites/{siteId}/machines/{machineId}/processes |
owlette process update <processId> | ready | process | PATCH /api/sites/{siteId}/machines/{machineId}/processes/{processId} |
owlette process delete <processId> | ready | process | DELETE /api/sites/{siteId}/machines/{machineId}/processes/{processId} |
owlette process schedule <processId> | ready | process | POST /api/sites/{siteId}/machines/{machineId}/processes/{processId}/schedule |
owlette process start <processId> | ready | process | POST /api/sites/{siteId}/machines/{machineId}/processes/{processId}/start |
owlette process stop <processId> | ready | process | POST /api/sites/{siteId}/machines/{machineId}/processes/{processId}/stop |
owlette process restart <processId> | ready | process | POST /api/sites/{siteId}/machines/{machineId}/processes/{processId}/restart |
owlette process kill <processId> | ready | process | POST /api/sites/{siteId}/machines/{machineId}/processes/{processId}/kill |
keys, users, and installer management
| command | status | reference page | public route or reason |
|---|---|---|---|
owlette key list | ready (superadmin keys only) | key | GET /api/account/api-keys |
owlette key create | ready (superadmin keys only; scopes inherited) | key | POST /api/account/api-keys |
owlette key update <keyId> | not available | key | session-only — PATCH /api/keys/{keyId} rejects api-key auth |
owlette key rotate <keyId> | not available | key | session-only — POST /api/keys/{keyId}/rotate rejects api-key auth |
owlette key revoke <keyId> | not available | key | session-only — DELETE /api/keys/{keyId} rejects api-key auth |
owlette user list | ready | user | GET /api/users |
owlette user get <uid> | ready | user | GET /api/users/{uid} |
owlette user promote <uid> | ready | user | POST /api/users/{uid}/promote |
owlette user demote <uid> | ready | user | POST /api/users/{uid}/demote |
owlette user assign-sites <uid> | ready | user | POST /api/users/{uid}/assign-sites |
owlette user remove-sites <uid> | ready | user | POST /api/users/{uid}/remove-sites |
owlette user delete <uid> | ready | user | DELETE /api/users/{uid} |
owlette installer list | ready | installer | GET /api/installer |
owlette installer latest | ready | installer | GET /api/installer/latest |
owlette installer upload <file> | ready | installer | POST /api/installer/upload, signed PUT, then PUT /api/installer/upload |
owlette installer set-latest <version> | ready | installer | POST /api/installer/{version}/set-latest |
owlette installer delete <version> | ready | installer | DELETE /api/installer/{version} |
webhook noun
owlette webhook is not registered in cli/src/index.ts yet. The public route family is live for developer preview, but CLI CRUD remains a Wave 3 follow-up so the command surface can settle with SDK examples.
| planned command | status | reference page | public route or reason |
|---|---|---|---|
owlette webhook create | planned | webhook | POST /api/webhooks?siteId=<siteId> |
owlette webhook list | planned | webhook | GET /api/webhooks?siteId=<siteId> |
owlette webhook get <webhookId> | planned | webhook | GET /api/webhooks/{webhookId}?siteId=<siteId> |
owlette webhook update <webhookId> | planned | webhook | PATCH /api/webhooks/{webhookId}?siteId=<siteId> |
owlette webhook delete <webhookId> | planned | webhook | DELETE /api/webhooks/{webhookId}?siteId=<siteId> |
owlette webhook rotate-secret <webhookId> | planned | webhook | POST /api/webhooks/{webhookId}/rotate-secret?siteId=<siteId> |
owlette webhook deliveries <webhookId> | planned | webhook | GET /api/webhooks/{webhookId}/deliveries?siteId=<siteId> |
owlette webhook delivery get <webhookId> <deliveryId> | planned | webhook | GET /api/webhooks/{webhookId}/deliveries/{deliveryId}?siteId=<siteId> |
owlette webhook retry <webhookId> <deliveryId> | planned | webhook | POST /api/webhooks/{webhookId}/deliveries/{deliveryId}/retry?siteId=<siteId> |
owlette webhook probe | planned | webhook; trigger page pending (Task 4.10) | top-level owlette trigger --via-api already uses POST /api/webhooks/probe?siteId=<siteId> |
invariants
- No registered CLI command calls
/api/admin/*. owlette chatcurrently calls the/api/cortex/conversations/*compatibility aliases;/api/hoot/conversations/*is the canonical family, and/api/chat/*is a second, older alias set.machine live-viewis the only registered stub;rg 'stubExit\(' cli/src/commandsshould only matchcli/src/commands/machine.ts.owlette listenandowlette triggerare registered commands, but their dedicated reference pages are still pending Tasks 4.9 and 4.10.owlette webhook ...is documented as a planned noun, not a registered command.
owlette cli — overview
owlette is the command-line client for the owlette.app api. It runs on macOS, linux, and windows and lets you authenticate, push roosts, manage sites and machines, mint api keys, and inspect audit logs from your terminal or ci pipeline.
auth
auth groups the three verbs that manage the active profile's stored credential. it acts on the user's local config — the cli's own state — and never touches a site or machine. tier: [ready] for all three verbs.