AgentSkyCLI reference
sky — agents like fly.io apps
npm i -g @agentsky/sky. The CLI speaks only the public API, so everything it does the raw API can do too.
auth
| command | what it does |
|---|---|
sky auth login | opens the browser to authorize this machine; mints a personal token (read+write) |
sky auth login --no-browser | prints a URL to open anywhere; polls until approved (headless/CI bootstrap) |
sky auth whoami | who the current token acts as, resolved universe, scopes |
sky auth logout | forgets the stored token (revoke it in Settings → API tokens) |
sky auth connect claude | connect your Claude Pro/Max subscription (runs claude setup-token, or paste a token) — eligible agents then run at $0 model usage |
sky auth connect chatgpt | connect your ChatGPT plan by uploading your local Codex sign-in (with consent) |
sky auth accounts | list connected model subscriptions and the agents they power |
sky auth disconnect <provider> | disconnect a model subscription (agents on it fail until switched to Platform) |
Config lives at ~/.config/sky/config.json. CI needs no login or config — set SKY_API_TOKEN (and optionally SKY_API_URL).
launch / deploy / clone
| command | what it does |
|---|---|
sky launch | scaffolds ./agent.toml if absent, creates the agent spec + its first session, stamps the agent id back into the file |
sky deploy | re-applies ./agent.toml to the existing agent (the prompt applies to sessions started after the save; idempotent) |
sky clone [--harness] [--new] [--dry-run] [-y] [--open] | clones your local agent (Claude Code first) into the cloud: instructions, model, secretless MCP servers — never secrets or history. Linked machines re-run it to sync the prompt; --new launches fresh |
agent
An agent is a reusable spec. Conversation verbs act on its default session.
| command | what it does |
|---|---|
sky agent create [--type --llm --name] [-f file] | create the spec only — sky session create starts the runtime |
sky agent list · show <id> | specs in the current universe, with session counts |
sky agent message <id> ["…"] [--file p…] [--image p…] [--system "…"] [--detach] | send one message (text, files, images, optional per-turn system text) to the default session and stream the turn until idle |
sky agent chat <id> [--system "…"] | interactive REPL with the default session |
sky agent archive <id> | retire the spec — read-only, running sessions unaffected (admin scope) |
sky agent destroy <id> | delete the spec; destroy its sessions first (admin scope) |
session
The pod-backed runtime of one agent. Creation is cheap — the pod starts on the first message.
| command | what it does |
|---|---|
sky session create <agent> [--title] [--message "…"] [--vcpus --memory] | create a session; --message seeds and starts the first turn |
sky session list [agent] · show <id> | sessions, with status and the default marker |
sky session message <id|agent> ["…"] [--file p…] [--image p…] [--system "…"] [--detach] | send one message (an agent id means its default session); files upload first and ride the message |
sky session chat <id|agent> [--system "…"] | interactive REPL over the standing stream |
sky files upload <path> · list [--session <id>] · get <id> · rm <id> · download <id> -o <path> | uploads you reference from a message; every receiving session keeps its own copy |
sky session interrupt <id|agent> | abort the in-flight turn |
sky session logs <id|agent> [-f] [--since 1h] | pod logs; -f follows live |
sky session archive <id> | irreversibly archive: no new messages, pod torn down, history stays readable |
sky session delete <id> | permanently delete the session, its events, and its sandbox |
routine
Run agents on a schedule — see Routines.
| command | what it does |
|---|---|
sky routine create <name> --agent <id>|--session <id> --message "…" [--cron "0 9 * * 1-5"] [--timezone tz] [--budget-cents n] | --agent starts a fresh session per fire; --session fires into one long-lived session |
sky routine list · show <id> | routines, with cron/target/state; show adds the last 5 runs |
sky routine run <id> | fire now, outside the schedule (works while paused) |
sky routine pause <id> · unpause <id> | suppress / resume scheduled fires (unpause resumes from the next occurrence) |
sky routine archive <id> | terminal: the schedule stops and the routine becomes immutable |
universe / secrets
| command | what it does |
|---|---|
sky universe list · create <slug> · switch <slug> · show | grouping boundary; switch scopes every later command |
sky secrets set <id> KEY=VALUE … | set values for keys declared in the spec (write-only) |
sky secrets list <id> · unset <id> KEY | set/unset status; values never come back |
A full session
$ npm i -g @agentsky/sky
$ sky auth login
Logged in as dev@example.com (universe: dev-3f2a)
$ sky launch
Scaffolded agent.toml — edit it anytime; re-apply with `sky deploy`.
Launched agent_cmtb2f0a8m9k7x51q4ez6r0d (hermes · deepseek-v4-pro) # spec + first session
$ sky agent message agent_cmtb2f0a8m9k7x51q4ez6r0d "What can you do?"
I'm a persistent research agent — give me a topic and I'll dig in.
$ sky secrets set agent_cmtb2f0a8m9k7x51q4ez6r0d NOTION_TOKEN=secret_…
set NOTION_TOKEN