Commands and Endpoints

Base Commands

Command	Purpose	API usage
roberto help	Show CLI usage	None
roberto version	Print CLI version	None
roberto capabilities	Print capability report object	None
roberto mcp	Start MCP stdio server	None

Auth Commands

Command	Purpose	API usage
roberto auth login	Device flow start + poll until authorized	POST /api/auth/device/start, POST /api/auth/device/poll
roberto auth status	Print locally stored user auth metadata	None (local store read)
roberto auth logout	Revoke refresh token and remove local auth state	POST /api/auth/logout (unless --local-only)
roberto auth refresh	Exchange refresh token for a new user token pair	POST /api/auth/refresh
roberto auth whoami	Resolve current user profile	GET /api/users/me (with one refresh retry)

Runtime Auth and Runtime Update Commands

Command	Purpose	API usage
roberto auth runtime-init	Exchange runtime bootstrap token for runtime session tokens	POST /api/runtime/bootstrap/exchange
roberto auth runtime-status	Show local runtime auth metadata (default) or remote runtime identity status (--remote)	None by default; GET /api/runtime/auth/status when --remote
roberto auth runtime-check-updates	Resolve update decision for runtime	POST /api/runtime/updates/check
roberto auth runtime-apply-update	Apply approved update plan and report applied version	POST /api/runtime/updates/check, POST /api/runtime/updates/apply, GET /api/runtime/updates/scripts, POST /api/runtime/updates/report
roberto auth runtime-agent-start	Start runtime target agent machine (self by default)	POST /api/runtime/agents/:id/start
roberto auth runtime-agent-stop	Stop runtime target agent machine (self by default)	POST /api/runtime/agents/:id/stop
roberto auth runtime-agent-status	Read runtime target agent machine status (self by default)	GET /api/runtime/agents/:id/status
roberto auth delegate list	List runtime delegation grants	GET /api/runtime/delegations
roberto auth delegate create	Create runtime delegation grant	POST /api/runtime/delegations
roberto auth delegate revoke	Revoke runtime delegation grant	DELETE /api/runtime/delegations/:id

Agents Commands

Command	Purpose	API usage
roberto agents list	List agents for authenticated user	GET /api/agents
roberto agents get --id <agent-id>	Get one agent	GET /api/agents/:id
roberto agents create ...	Create agent	POST /api/agents
roberto agents update ...	Update mutable agent fields	PATCH /api/agents/:id
roberto agents delete --id <agent-id>	Delete agent	DELETE /api/agents/:id
roberto agents provision --id <agent-id>	Provision runtime machine	POST /api/agents/:id/provision
roberto agents start --id <agent-id>	Start runtime machine	POST /api/agents/:id/start
roberto agents stop --id <agent-id>	Stop runtime machine	POST /api/agents/:id/stop
roberto agents status --id <agent-id>	Read machine status	GET /api/agents/:id/status
roberto agents clone --id <agent-id> [--name <name>]	Clone agent into a new machine-backed agent	POST /api/agents/:id/clone
roberto agents gateway-access --id <agent-id>	Fetch gateway URL/token for agent shell/dashboard access	GET /api/agents/:id/gateway-access
roberto agents connect-telegram --id <agent-id>	Connect Telegram channel for online agent	POST /api/agents/:id/connect-telegram
roberto agents whatsapp-qr --id <agent-id>	Generate/retrieve WhatsApp QR payload	POST /api/agents/:id/whatsapp-qr
roberto agents whatsapp-wait --id <agent-id>	Wait/poll for WhatsApp connect completion	POST /api/agents/:id/whatsapp-wait
roberto agents runtime-update-status --id <agent-id>	Evaluate runtime update state for agent	GET /api/agents/:id/runtime-update-status
roberto agents runtime-update-grant --id <agent-id>	Issue one-time runtime update grant token	POST /api/agents/:id/runtime-update-grant

Billing Commands

Command	Purpose	API usage
roberto billing status	High-level billing readiness + next action	GET /api/billing/summary
roberto billing summary	Raw billing snapshot	GET /api/billing/summary
roberto billing usage-summary [--days <7-365>]	Usage rollups for selected range	GET /api/billing/usage-summary
roberto billing setup [--plan ...]	Checkout (when plan specified) or portal (when already subscribed)	POST /api/billing/checkout or POST /api/billing/portal
roberto billing checkout --plan ...	Create checkout session	POST /api/billing/checkout
roberto billing credits-checkout --package ...	Create one-time credits checkout	POST /api/billing/credits/checkout
roberto billing portal	Create billing portal session	POST /api/billing/portal
roberto billing sync	Force billing sync	POST /api/billing/sync
roberto billing runtime-requests	List runtime spend approval requests	GET /api/billing/runtime-requests
roberto billing runtime-request --id <request-id>	Fetch one runtime spend request	GET /api/billing/runtime-requests/:id
roberto billing runtime-approve --id <request-id>	Approve and execute runtime spend request	POST /api/billing/runtime-requests/:id/approve
roberto billing runtime-deny --id <request-id>	Deny runtime spend request	POST /api/billing/runtime-requests/:id/deny
roberto billing runtime-policy-get --controller-agent-id <agent-id>	Fetch standing runtime spend policy	GET /api/billing/runtime-spend-policies/:controllerAgentId
roberto billing runtime-policy-set --controller-agent-id <agent-id> ...	Create/update standing runtime spend policy	POST /api/billing/runtime-spend-policies/:controllerAgentId
roberto billing runtime-policy-revoke --controller-agent-id <agent-id>	Revoke standing runtime spend policy	DELETE /api/billing/runtime-spend-policies/:controllerAgentId

Task Commands

roberto task provides dashboard-equivalent action dispatch with action IDs.

Command	Purpose	API usage
roberto task catalog	List supported action IDs + input schema	None
roberto task run --action <action-id> --input-json <json>	Execute a mapped action (users/agents/billing)	Uses the same endpoints as Users, Agents, and Billing commands

Examples:

roberto task run --action agents.start --input-json '{"id":"agent_123"}'
roberto task run --action billing.checkout --input-json '{"planCode":"pro"}'

Common Flags

Flag	Where used	Meaning
--control-plane-url <url>	Most auth/agents/billing/task commands	Override API host
--store-path <path>	Most auth/agents/billing/task commands	Override user/runtime store file path
--local-only	auth logout	Skip remote logout call and remove only local state
--runtime-id <id>	auth runtime-init	Runtime identity ID
--remote	auth runtime-status	Query control plane runtime status endpoint instead of local store metadata
--bootstrap-token <token>	auth runtime-init	One-time bootstrap token
--runtime-version <v>	auth runtime-init	Report current runtime release version
--current-version <v>	Runtime update commands	Explicitly set current runtime version
`—channel stable	canary	security`
--target-version <v>	auth runtime-apply-update, agents runtime-update-grant	Request exact target version
--agent-id <id>	auth runtime-agent-start, auth runtime-agent-stop, auth runtime-agent-status	Runtime target agent id (defaults to local runtime agent)
--runtime-id <id>	auth delegate list/create	Runtime identity id for delegation scope
--delegation-id <id>	auth delegate revoke	Delegation id to revoke
--scope-json <json>	auth delegate create	Delegation scope payload JSON
--ttl-seconds <n>	auth delegate create	Delegation lifetime in seconds
--expires-at <iso>	auth delegate create	Explicit delegation expiry override
--approve	auth runtime-apply-update	Required confirmation for executing update scripts
--grant-token <token>	auth runtime-apply-update	One-time grant token issued by control plane
`—plan starter	pro	team`
`—package credits_3000	credits_6000	credits_12000`
--days <7-365>	billing usage-summary	Usage summary time window
--status <status>	billing runtime-requests	Filter runtime requests by status
--limit <1-100>	billing runtime-requests, auth delegate list	Limit list response size

Output Model

• Success responses print JSON to stdout.
• Validation and command errors print to stderr and set non-zero exit status.
• Most authenticated calls perform one refresh retry on 401 using local refresh token state.