CLI Reference

The CLI package is @common-os/cli. It declares the cos binary and sets the Commander program name to commonos.

Auth

commonos auth login --key cos_live_xxx --url http://localhost:3001
commonos auth whoami
commonos auth logout

Credentials are stored in:

~/.commonos/config.json

Environment variables override stored config:

COMMONOS_API_KEY=cos_live_xxx
COMMONOS_API_URL=http://localhost:3001

Fleets

commonos fleet create --name product-team --provider aws --region eu-west-1
commonos fleet ls
commonos fleet status flt_xxx

Agents

commonos agent deploy --fleet flt_xxx --role backend-engineer
commonos agent deploy --fleet flt_xxx --role manager --tier manager
commonos agent deploy --fleet flt_xxx --role researcher --prompt "You research markets."
commonos agent deploy --fleet flt_xxx --role hermes-researcher --runtime hermes --model openai/gpt-5.4-mini
commonos agent deploy --fleet flt_xxx --role guest --image ghcr.io/acme/agent:latest

commonos agent ls --fleet flt_xxx
commonos agent logs agt_xxx --fleet flt_xxx
commonos agent terminate agt_xxx --fleet flt_xxx

--runtime can be native, openclaw, hermes, or guest. --image without --runtime keeps the legacy behavior and sets integrationPath: "guest", running the image as the guest-runtime container in the agent pod. The image must run a long-lived process that uses the injected AGENT_ID, AGENT_TOKEN, and API_URL values.

Tasks

commonos task send agt_xxx "Analyze the market" --fleet flt_xxx
commonos task ls agt_xxx --fleet flt_xxx

World

commonos world snapshot flt_xxx
commonos world stream-url flt_xxx

Notes

agent logs currently prints task history through the task list route.
CLI output is JSON for most commands.
The CLI exits if it cannot find an API key in env or config.