CLI reference — sky

npm i -g @agentsky/sky. The CLI uses the public API for agent management and the AgentSky app import endpoint for local conversations.

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 Developer → API keys)
`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; sky config prints its location and current values. CI needs no login or config — set SKY_API_TOKEN (and optionally SKY_API_URL, or SKY_CONSOLE_URL to point sky auth login at a different console).

sky auth login always mints a read + write token. That covers every command here except sky agent archive and sky agent destroy, which need admin and will answer insufficient_scope on a logged-in CLI. Mint an admin key under Developer → API keys and pass it for those calls:

bash

SKY_API_TOKEN=ast_… sky agent destroy agent_…

setup

command	what it does
`sky setup [skill\|logins\|import\|secrets ...]`	bring this machine's agents to AgentSky: install the AgentSky skill and register its MCP server, connect the plans they are signed in to, send your own skills and global instruction files to your workspace, and save the tool keys you pick to your vault — every step when none is named, each asked about first
`sky setup --key <key>`	use a setup key from agentsky.dev/setup
`sky setup --dry-run`	say what would be done; write and send nothing
`sky setup --json`	print progress as one JSON object per line; never asks

Narrow a run with --agent claude_code\|codex\|cursor, --plan claude\|chatgpt\|cursor (connect only these plans), --secret <name...> (save these tool keys; asked one by one when omitted) or --no-claude (leave the Claude plan alone); -y skips the questions. Requires CLI 2.7.0 or later. No progress event carries a credential.

The skill step (CLI 2.9.0 or later) writes the agentsky skill to skills/agentsky/ under CLAUDE_CONFIG_DIR (default ~/.claude), CODEX_HOME (default ~/.codex) and ~/.cursor, with catalog.md beside it: every agent you can hire as of that run, your own workspace's first. It then registers the AgentSky MCP server as agentsky with claude mcp add and codex mcp add, replacing an earlier registration, so the skill can hire over the MCP tools; Codex reads the token from AGENTSKY_API_KEY, so set it in the shell that runs codex. Run the step again to refresh the catalog and the registration.

import

command	what it does
`sky import [--harness claude_code\|codex\|all] [--limit 10]`	list recent local conversations, choose one and confirm its upload; prints an AgentSky review link
`sky import --session <id> [--url <app-origin>] [-y]`	import a specific recorded conversation; `--yes` confirms the transfer without prompting
`sky import --all --limit <n> [-y]`	import up to the selected limit after confirming the listed conversations

Requires CLI 2.4.0 or later, sky auth login with an unrestricted personal write token, and an existing AgentSky profile. Open AgentSky once with the same account before the first import. Set --url to the AgentSky app origin (or use AGENT_USE_URL); this is not the developer API URL. Local development permits an HTTP loopback origin; remote destinations require HTTPS.

The CLI reads Claude Code records under CLAUDE_CONFIG_DIR (default ~/.claude) and Codex records under CODEX_HOME (default ~/.codex). Recorded descendants are included. It snapshots and redacts the selected JSONL locally before uploading, rejects incomplete records and enforces a 16 MiB limit. Non-interactive use requires --yes; when multiple conversations are found, select one with --session or choose --all. An explicit session ID is searched across the recorded history, independently of the recent-list limit.

The browser lets you review or discard the import before continuing. Continuation attaches the full redacted record and asks the receiving agent to read it. Local project files, login credentials and a native resumable checkpoint are not transferred; an automatic wrapper does not infer the task's semantic completion state.

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
`sky config`	where the config file is and what is in it

harness

A workspace-defined harness is an ACP agent the workspace publishes from its own profile; the platform builds, verifies and versions it. Behind the WORKSPACE_HARNESSES switch.

command	what it does
`sky harness init [dir]`	write a `harness.json` profile skeleton to validate and fill in
`sky harness verify [dir] [--handle @listing]`	validate the profile locally; with `--handle`, run the listing's conformance suite through the API and print its checks
`sky harness push [dir] [--version X]`	create the harness if its handle is new, or submit a new version, and print the version's state
`sky harness connect --session sess_… --token hct_… -- <agent command>`	run an ACP agent that speaks over stdio as that session's brain (a remote harness): dial the session's relay, pipe the agent's JSON-RPC both ways, reconnect with a fresh agent after a drop, and stop when the relay refuses the token or the session; without `--session` it reads `AGENTSKY_HARNESS_RELAY_URL` and `AGENTSKY_HARNESS_TOKEN`; `--once` exits instead of reconnecting. The agent must do all its work through the session's sandbox (ACP `fs/` and `terminal/`)

worker

A worker pool lets a workspace's own machines run the pod: the machine connects out to the platform and runs the exact image the platform names. Behind the WORKER_POOLS switch.

command	what it does
`sky worker start --pool wpool_… [--label …] [--token …]`	connect this machine to a worker pool (token from `SKY_WORKER_TOKEN` or `--token`), run the pod in Docker when a session is assigned, tunnel its HTTP and stream back to the platform, and stop on Ctrl-C

agent

An agent is a reusable spec. Conversation verbs act on its default session.

command	what it does
`sky agent create [--type --llm --name] [--capability id…] [-f file]`	create the spec only — `sky session create` starts the runtime
`sky agent list`	specs in the current universe, with session counts
`sky agent show <id>`	one spec: engine, model, capabilities, sessions
`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 — see auth)
`sky agent destroy <id>`	delete the spec; delete its sessions first. A spec whose sessions were deleted still owns their rows, so it is archived rather than removed and keeps appearing in `sky agent list` (admin scope — see auth)

session

The pod-backed runtime of one agent. Creation starts provisioning by default. Use --deferred to leave the session idle without a pod until its first turn. --message starts that turn immediately and provisions even with --deferred.

command	what it does
`sky session create <agent> [--title] [--message "…"] [--deferred] [--vcpus --memory] [--file path[:/mount]…] [--repo url[@ref]…] [--repo-token t]`	create a session (eager by default); `--deferred` waits for the first turn; `--message` starts that turn immediately, even with `--deferred`; `--file` uploads and mounts files read-only in the working directory, `--repo` clones GitHub repositories there (the token never enters the sandbox)
`sky session list [agent]`	sessions, with status and the default marker
`sky session show <id>`	one session: status, model, budget, mounted resources
`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 session interrupt <id\|agent>`	abort the in-flight turn
`sky session read <id\|agent> [--wait] [--timeout s] [--json]`	what the agent has said since the last message it was sent; `--wait` holds until its turn finishes (600 s by default)
`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

session resources

The files and GitHub repositories mounted into a session's working directory.

command	what it does
`sky session resources list <ref>`	what is mounted, oldest first
`sky session resources get <ref> <rid>`	one resource
`sky session resources add <ref> <path[:/mount]>`	upload and mount a file before the next turn
`sky session resources rm <ref> <rid>`	unmount a file (repositories stay for the session's life)
`sky session resources rotate <ref> <rid> <token>`	replace a repository's token; the new policy is pushed to the live pod

session ports

Local servers the agent runs inside the session's pod, each exposed on an origin of its own (https://app-<id>.agentsky.dev). A private port — the default — admits one browser per entry link; a public port admits anyone with the address.

command	what it does
`sky session ports list <ref>`	the exposed ports, oldest first
`sky session ports expose <ref> <port> [--public]`	expose a port the agent's server listens on (1024–65535, never the pod's own) as private, or public with the flag — either way the visibility is set, so re-running makes a public port private; prints its address
`sky session ports open <ref> <port>`	print an entry link: single-use and good for a minute on a private port, the plain address on a public one
`sky session ports revoke <ref> <port>`	stop exposing it; the address answers 404 from then on

files

Uploads you reference from a message. An upload is write-once; every session that receives it keeps its own readable copy.

command	what it does
`sky files upload <path> [--expires s]`	upload a local file; prints the `file_…` id
`sky files list [--session <id>] [--limit n] [--page cursor]`	your uploads, or one session's files
`sky files get <id>`	one file's metadata
`sky files rm <id>`	soft-delete an upload
`sky files download <id> -o <path>`	a session file's bytes

task

A task's files: one folder every session of the task shares. A task is addressed by its first session's id.

command	what it does
`sky task files <task>`	the task's current files
`sky task get <task> <path> [-o <out>]`	one file's bytes, printed or written to `<out>`
`sky task put <task> <path> <local>`	write a local file to `<path>`; every session of the task sees it at its next turn
`sky task rm <task> <path>`	remove a path; its history is kept

artifact

A named, versioned result published from a task's files, with an optional public link.

command	what it does
`sky artifact list [--task <task>]`	the workspace's artifacts, or one task's
`sky artifact publish <task> --name "…" --path <path>… [--entry <path>]`	publish those task files; the same name again adds a version
`sky artifact get <id> <path> [-o <out>]`	one file of the artifact's current version
`sky artifact share <id> [--off]`	print a public link anyone can open; `--off` stops it, and sharing again gives a new link
`sky artifact rm <id>`	delete the artifact

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]`
`sky routine list`	routines, with cron, target and state
`sky routine show <id>`	one routine, plus its last 5 runs
`sky routine run <id>`	fire now, outside the schedule (works while paused)
`sky routine pause <id>`	suppress scheduled fires (manual runs still work)
`sky routine unpause <id>`	resume from the next occurrence — missed fires are not backfilled
`sky routine archive <id>`	terminal: the schedule stops and the routine becomes immutable

catalog

The agents you can hire by @handle. Reading needs no login; logged in, you also see your own workspace's listings. Hire one with sky session create @handle --message "…".

command	what it does
`sky catalog search [words…] [--category id] [--json]`	every hireable agent, or only those matching the words
`sky catalog show <handle> [--json]`	what one agent does and does not do, with the command that hires it
`sky catalog categories`	the categories a listing can carry
`sky catalog publish <agent> --handle <handle> --tagline "…" [--description "…"] [--category id]… [--does "…"]… [--does-not "…"]… [--example "…"]…`	list one of your agents under a handle, visible to your workspace; publishing again replaces the listing. A handle is 2 to 40 lower-case letters, digits or underscores
`sky catalog unpublish <handle>`	take your listing down; the agent itself is untouched
`sky catalog delist <engine> --reason "..."`	immediately hide a harness and reject new acquisition; platform operators only, verified after writing
`sky catalog relist <engine> --reason "..."`	restore a runnable harness; platform operators only, verified after writing

skill

Teaches the agents installed on this machine to hand work to AgentSky agents.

command	what it does
`sky skill install [--agent claude_code\|codex\|cursor…] [--dry-run] [--json]`	add the AgentSky skill to each installed agent, or only the ones named; `--dry-run` writes nothing

goal

Give a session a standing objective. After each turn the platform checks the work against the goal's criteria and either takes another turn or stops.

command	what it does
`sky goal set <session> "<objective>" [--criterion "…"]… [--check "<text> :: <command>"]… [--max-iterations n] [--max-spend-cents n] [--max-tokens n] [--max-minutes n]`	set the goal, replacing any existing one; work starts right away. Omit criteria and they are written from the objective. A `--check` command runs in the workspace and must exit 0
`sky goal get <session> [--json]`	the goal, its limits and usage, and what the last check found
`sky goal edit <session> [--objective "…"] [--criterion …] [--check …] [limits]`	change it in place; iterations and spend so far carry over. A limit of `none` lifts it
`sky goal pause <session>`	stop taking turns and interrupt the run the goal started
`sky goal resume <session>`	start taking turns again; a deadline moves out by the paused time
`sky goal clear <session>`	stop the goal for good

workspace

sky workspace is the preferred user-facing alias for the sky universe commands.

command	what it does
`sky workspace list`	workspaces you can reach (alias of `sky universe list`)

universe

command	what it does
`sky universe list`	universes you can reach
`sky universe create <slug>`	create one
`sky universe switch <slug>`	scope every later command to it
`sky universe show`	the current universe
`sky universe members [slug]`	everyone in the workspace with their role, and the waiting invitations (owners and admins)
`sky universe invite <email>… [--role admin\|member] [--send-email] [--universe slug]`	invite people by email (owners and admins); prints each person's `sky universe join` token
`sky universe uninvite <inviteId> [--universe slug]`	withdraw an invitation nobody has taken up
`sky universe role <member> <admin\|member> [--universe slug]`	change a member's role, by user id or email (owner only)
`sky universe remove <member> [--universe slug]`	remove a member, by user id or email (owner only)
`sky universe join <token>`	accept an invitation sent to your verified email

policy

Rules a workspace's sessions, or one session, run under. Without --session a command acts on the current workspace's rules.

command	what it does
`sky policy list [--session <ref> [--effective]] [--universe slug]`	the rules; `--effective` shows every layer a session runs under
`sky policy add --name "…" --kind TOOL_CALL\|SPEND_CAP\|CALL_COUNT\|CAPABILITY --config '<json>' [--position n] [--disabled] [--session <ref>]`	add a rule (workspace owner, or the session's owner). Configs: `{"action":"deny","matcher":"Bash","commandPatterns":["rm -rf *"]}`, `{"hardCapUsdMicros":5000000}`, `{"limitPerSession":200}`, `{"platform.orchestration":"deny"}`
`sky policy enable <ruleId> [--session <ref>]`	switch a rule on
`sky policy disable <ruleId> [--session <ref>]`	switch a rule off; it is kept so it can be switched on again
`sky policy rm <ruleId> [--session <ref>]`	delete a rule

secrets

command	what it does
`sky secrets set <id> KEY=VALUE …`	set values for keys declared in the spec (write-only)
`sky secrets list <id>`	which keys are set — values never come back
`sky secrets unset <id> KEY`	remove one key

A full session

bash

$ 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