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
owlette noun is registered yet.
- reference page - linked when a dedicated per-command page exists;
pending means the command is registered but its dedicated page is not created yet.
| 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> |
| 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 |
| 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} |
| 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: live-view-webrtc |
| 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} |
| 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} |
| 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 |
| command | status | reference page | public route or reason |
|---|
owlette key create | ready | key | POST /api/keys |
owlette key list | ready | key | GET /api/keys |
owlette key rotate <keyId> | ready | key | POST /api/keys/{keyId}/rotate |
owlette key revoke <keyId> | ready | key | DELETE /api/keys/{keyId} |
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} |
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> |
- No registered CLI command calls
/api/admin/*.
owlette chat uses canonical /api/cortex/conversations/* routes; /api/chat/* is compatibility-only.machine live-view is the only registered stub; rg 'stubExit\(' cli/src/commands should only match cli/src/commands/machine.ts.owlette listen and owlette trigger are 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.
