| name | atmos-cli |
| version | 1.0.0 |
| description | Operate Atmos product state via the `atmos` CLI (projects, workspaces, terminals, runs, settings, git, headless control). Use when the agent must create or manage Atmos resources without the UI. Do not use for desktop GUI capture/click (atmos-desktop-use), in-page browser DOM (atmos-browser-use), or canvas drawing (atmos-canvas-agent).
|
Atmos CLI (product control)
Control Atmos product state with the atmos binary. Prefer typed L1 resource
commands. Use atmos call only as an escape hatch when no L1 verb exists.
Default path: status → project/workspace L1 → terminal/run → settings
Escape hatch: atmos call <wire_action> --data '{…}'
Not this skill: canvas · desktop-use · browser-use
Prerequisites
atmos on PATH (atmos --version).- Atmos Server up (
atmos runtime ensure or Desktop).
- Auth when required:
--api-token / ATMOS_API_TOKEN / ATMOS_LOCAL_TOKEN.
- Fresh shell per tool call — re-run full commands.
Envelope (always JSON)
Every command prints one JSON object to stdout:
| Field | Meaning |
|---|
ok | success |
command | what ran |
result | payload when ok |
error.code / error.message | when failed |
fix | plain-language recovery |
next_actions | suggested next commands (templates + params) |
Exit code 0 iff ok: true. Prefer following next_actions and fix.
Details: references/envelope.md.
Decision tree (load references on demand)
Golden path (headless)
atmos status
atmos project validate-path --path /path/to/git/repo
atmos project create --name my-app --path /path/to/git/repo
atmos workspace create --project <project-guid> --name feature-x --branch feature-x
atmos context set --project <project-guid> --workspace <workspace-guid>
atmos terminal create --workspace <workspace-guid>
atmos settings bootstrap
Destructive deletes require --yes.
Critical rules
- Prefer L1 (
project create, not inventing WebSocket clients).
- Follow
next_actions — IDs are often pre-filled in params.
--yes for delete/destroy or you get CONFIRMATION_REQUIRED.- Set context with
atmos context set or flags --project / --workspace / env.
- Do not start every task with
actions list + call.
Anti-patterns
- ❌ Driving the Web UI (or desktop-use) for basic project/workspace CRUD
- ❌ Dumping the full wire-action catalog into context
- ❌ Using
atmos call when an L1 command exists
- ❌ Omitting
--yes on deletes then retrying blindly without reading fix
- ❌ Mixing this skill with canvas/desktop-use without need
Errors (short)
| Code | Recovery |
|---|
SERVER_UNREACHABLE | atmos runtime ensure |
UNAUTHORIZED | set token flags / env |
CONFIRMATION_REQUIRED | re-run with --yes |
CONTEXT_REQUIRED | pass --project / --workspace or context set |
UNKNOWN_ACTION | atmos actions list --filter … then fix call name |
More: references/errors.md.
Related skills
| Skill | When |
|---|
atmos-canvas-agent | Live canvas drawing |
atmos-desktop-use | Local OS GUI capture/click |
atmos-browser-use | Page CDP control |
atmos-review-fix | Review-session agent flows |
References (on-demand)
Skill source: skills/atmos-cli/ (synced to ~/.atmos/skills/.system/atmos-cli/ with other system skills).
