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, and the workspace a key is fixed to |
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 connect <provider> --browser | sign a plan in on the provider's own page (claude, chatgpt, cursor, grok, muse): the platform runs the provider's CLI in a short-lived sandbox and stores the result. --account new adds another account, --account <id> re-signs one, --label names it, --no-open only prints the link |
sky auth accounts | list connected model subscriptions and the agents they power |
sky auth usage <provider> | plan allowance left in each usage window (--account <id>, --json) |
sky auth switch-to-credits <provider> | move the agents on a subscription onto platform credits, restarting their running sessions (--account <id>, -y) |
sky auth disconnect <provider> | disconnect a model subscription (agents on it fail until switched to credits or reconnected) |
sky auth apps | the registered apps you let into your account, with the scopes you allowed |
sky auth revoke-app <clientId> | remove an app's access to your account; its tokens stop working at once (admin scope) |
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:
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 for Claude Code and as [mcp_servers.agentsky] in Codex's config.toml (the token in its http_headers, so Codex needs no environment variable), replacing an earlier registration, so the skill can hire over the MCP tools. 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 [--start] | scaffolds ./agent.toml if absent, creates the agent spec + its first session (idle until the first message; --start boots it now), stamps the agent id back into the file, keeping its comments |
sky deploy | re-applies ./agent.toml to the existing agent, type and llm included (the prompt, model and skills apply to sessions started after the save; an unchanged file changes nothing) |
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 |
capabilities
| command | what it does |
|---|---|
sky capabilities [--attention] [--json] | deprecated, still runs: sky plugins list --view yours (--attention keeps what needs you); prints one line on stderr naming 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 |
trace
A task trace correlates the work of a local agent with the cloud sessions it starts. By default it holds metadata only — span and tool names and session ids. Prompts, tool output and chosen files are sent only when you name them with --capture, redacted on your machine and again on arrival. A trace and everything in it is deleted after 30 days and is never exported. Behind the TASK_TRACES switch.
| command | what it does |
|---|---|
sky trace start [--name …] [--source claude-code] [--hooks [settings]] [--capture prompts,tool_output,files] [--file path]… [--dir path]… | start a trace, mint this machine's grant and record a root span; --hooks installs the Claude Code hooks (default ./.claude/settings.local.json); --capture also sends that content, and the files scope reads only the --file files and files under --dir folders, never credential, key, cookie or agent-state files |
sky trace hook | record one Claude Code hook event read from stdin; run by the installed hooks, never fails and prints nothing; stops recording once the grant is revoked or expired |
sky trace flush | send what the local spool holds (up to 32 MiB, kept 24 hours), retrying with backoff |
sky trace status | the running trace, pending events, and what was dropped, given up or refused |
sky trace show [trc_…] [--json] | the trace's spans, the sessions and tasks they reach, cost counted once per session, and gaps |
sky trace stop | end the root span, send what is left and revoke this machine's grant |
The trace library is separate: every local Claude Code and Codex session you choose to sync, kept in a workspace and searchable by its members. Sync reads only ~/.claude/projects and ~/.codex/sessions / archived_sessions, redacts on your machine and again on arrival, and routes each session by the repository's .agentsky.json, then the first --route whose match is in the folder path or git remote, then --default (otherwise it stays local).
| command | what it does |
|---|---|
sky trace sync --enable [--route match=workspace]… [--default workspace | --keep-local] | turn sync on for this machine and save its routing; prints the folders it reads and where each session goes |
sky trace sync [--full] [--session id-or-path]… [--limit n] [--dry-run] [--quiet] | upload new or changed sessions (unchanged files and content are skipped); --install-schedule also sweeps every 15 minutes with a weekly full re-read (macOS); --hook runs from a Claude Code SessionEnd/Stop hook or Codex notify and returns at once; --status reports what was stored where; --disable stops uploading |
sky trace search <query…> [--workspace slug] [--limit n] [--cursor …] [--json] | sky context search --scope traces in a workspace's library, newest first |
sky trace library [--workspace slug] [--limit n] [--json] | the sessions in a workspace's library, most recently updated first |
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…] [--file-id file_…] [--image p…] [--system "…"] [--plan|--build] [--detach] | send one message (text, files, images, optional per-turn system text) to the default session and stream the turn until idle; --plan asks for a reviewable plan instead of changes |
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 edit <id> [--name n] [--engine agentType] [--model llm] [--thinking effort|default] | change an agent's name, engine, model or thinking level, as its Library folder does (PATCH /agents/{id}) |
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] [--no-defaults] [--budget-cents n] | create a session (eager by default); --deferred waits for the first turn; --no-defaults attaches none of the workspace's defaults (environment, vault, files, skills, team memory); --budget-cents caps what it may spend; --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…] [--file-id file_…] [--image p…] [--system "…"] [--plan|--build] [--detach] | send one message (an agent id means its default session); files upload first and ride the message; --file-id attaches a file already uploaded, by id. --plan runs the turn in plan mode: the agent inspects and answers with a plan, then waits for a choice to implement; --build overrides a session left in plan mode |
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 |
sky session share <id|agent> [--view] [--rotate] [--off] | print the session's share link, turning sharing on; --view makes it read-only, --rotate replaces it, --off turns it off |
sky session usage <id|agent> [--limit n] [--json] | what the session has cost so far, and its newest billed entries |
sky session access <id|agent> [--private|--members] [--add-viewer email…] [--remove-viewer email…] | who may use the session and what you are to it; the flags change it (owner) |
sky session shared [--limit n] | sessions other people shared with you to read |
sky session people <id|agent> [--json] | everyone who may send the session turns (the people @ can name and it can be assigned to), marked here when they have it open and assigned for its assignee |
sky session assign <id|agent> [user-id] [--clear] | assign the session to one of its people (a user id from sky session people): they see it waiting on them and are notified; --clear unassigns it |
sky session model <id|agent> [model] [--thinking level] | print the session's model and thinking level, or switch them; the next turn uses the new ones (--thinking default returns to the agent's own) |
sky session handoff <id|agent> <target-agent> [--from-message id] [--model id] [--thinking level] [--no-wait] | hand the session's conversation and workspace files to another agent (an agent id or catalog handle), optionally on a chosen model and thinking level, and print the new session; it forks natively when both run the same harness, otherwise carries a written summary |
sky session continue-here <id|agent> [--dir <folder>] | moves an idle Claude Code or Codex session you own onto this computer: restores its exact conversation under ~/.claude or ~/.codex and its workspace (where carried) into --dir, then prints the claude --resume or codex resume command; the cloud session takes no more turns |
sky session cloud-copy <id|agent> [--json] | what is kept in the cloud for a chat synced from your own computer: its working folder (restored at /workspace/<name>) and its native session (resumed exactly on the same agent), or none stored yet; only the chat's owner sees it |
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 |
session workspace
The files the agent works on in its pod. Reads never wake a parked session (session_parked: send it a message first); patch and import do.
| command | what it does |
|---|---|
sky session workspace ls <ref> [path] [--hidden] | list a directory (default: the workspace root), up to 200 entries |
sky session workspace cat <ref> <path> [--out file] | print a file up to 1 MB, or save it |
sky session workspace changes <ref> | git status and diff summary of each repository in the workspace |
sky session workspace patch <ref> [repo] [--out file] | the work in a repository since its base branch as a git patch, ready for git apply |
sky session workspace import <ref> <dir> [--name n] | copy a local folder in as a git repository; files git ignores, .git and node_modules stay behind; over 25 MB it goes up in resumable parts |
session browser
The sandbox browser inside a session pod. Start it to get an entry link for interactive use; the agent uses its own browser tools without needing this.
| command | what it does |
|---|---|
sky session browser show <ref> [--json] | the current browser status and entry URL |
sky session browser start <ref> [--json] | start (or provision) the browser; prints its entry URL |
sky session browser stop <ref> | stop it |
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 <paths…> [--expires s] | upload local files and folders (every file inside, four at a time), with no application file-size cap and an exact integer byte count, resuming where an interrupted run left off; prints each file_… id |
sky files usage | how many files the workspace holds and the space they take; there is no storage limit |
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, and the requests waiting on you. 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 |
sky task show <task> [--json] | the task's sessions and its open requests addressed to you: questions, approvals, apps to connect |
sky task story <task> [--all] [--order <asc or desc>] [--cursor <c>] [--limit <n>] [--by-session] [--json] | what happened in the task and who did each thing: messages by person and agent, tool calls, helpers and handoffs, requests and answers, mentions, file versions, artifacts and comments, connector calls, meetings, work graph events (GitHub pull requests and checks among them). --all prints every page from the start |
sky task graph <task> [--related] [--cursor <c>] [--limit <n>] | JSON events and inferred cross-thread associations with exact reference evidence, association scores and correction versions; source permissions apply. --related returns only inferred or confirmed associations |
sky task link <task> <event> --version <n> [--action <confirm or remove or move>] [--to <task>] | correct an association in your personal task view; default action is confirm. Use the current graph version (0 before any correction); move requires --to. A stale version requires reading the graph again; source permissions do not change |
sky task find-email <task> [query] [--connection <id>] [--json] | search your Gmail, or a Gmail a teammate shared with the task's workspace, for a thread to attach (Gmail search syntax; read-only) |
sky task attach-email <task> <thread> [--connection <id>] | keep a Gmail thread (its id or Gmail address) in the task's files as plain text, email/<subject>-<thread>.md; the story names you as the one who attached it; nothing is sent |
sky task export <task> [-o dir] [--tier gold|silver|exploratory] [--redact name=alias] | the task's session record as a Harbor task directory: instruction, rubric and judge, files, rollout, one step per revision; names and secrets scrubbed |
sky task threads <task> [--json] | the task's threads from the session record: root first, then every helper, handoff and child with its source, agent, status and spend |
sky task decide <session> <kind> [--target <session>] [--yes|--no] [--reason "…"] [--key <key>] | record what you did with a session's result: adopt, rerun, revise, discard, vote, did_the_job, approve; nothing is recorded unless you run it |
sky task outcome <session> <kind> [--ref <ref>] [--key <key>] | record what became of a session's result: pr_merged, deployed, reopened, later_failure, shipped |
sky task answer <task> <request> (--option <id> | --text "…") [--note "…"] | answer an open request; the asking session continues with the answer |
sky task dispute <task> --reason "…" [--session <id>] | dispute an agent fee — report the task was not completed (allowed within 72 hours of the first result; name the session when the task has more than one fee) |
sky task verdict <task> yes|no | record whether the task did the job (replaces an earlier answer) |
skills
Every skill is a plugin, skill:<id>: upload it with sky plugins upload, then attach it to agents by id ([[skills]] in agent.toml). The old store commands still run their sky plugins replacement and say so on stderr.
| command | what it does |
|---|---|
sky skills upload <dir> / sky skills list | deprecated, still runs: sky plugins upload <dir> / sky plugins list --view yours --source skill |
sky skills attach <skill> --agent <id> | add a stored skill to an agent; new sessions load it |
sky skills detach <skill> --agent <id> | remove a stored skill from an agent; new sessions stop loading it |
sky skills usage [--since <iso>] [--json] | how often agents looked up each skill and which names they asked for that do not exist (last 30 days by default) |
sky plugins install <source> [--mcp-token <server=token>]... [--json] | install or update a Claude Code plugin from github:owner/repo[/path][@ref] or a github.com URL: its skills and commands become workspace skills on for every new session; prints the connectors it uses and which to connect |
sky plugins list [--json] | the workspace's installed plugins and their skills |
sky plugins list --view <yours|discover> [--q <text>] [--use <use>] [--source <source>] [--cursor <cursor>] [--include <names>] [--json] | everything agents can use (yours: added, off or needing you) or can add (discover): apps, tools, chat apps, bundles, skills, MCP servers, browser logins and Mac features, each with its provider and price; --include connections,granted,shared,services also prints your connected accounts and credit, the connections granted to this key, what you share and the workspace's services |
sky plugins show <id> [--json] | one plugin by id (app:gmail, tool:exa.web, chat:slack, bundle:<name>, skill:<id>, mcp:<id>, mac:meetings, browser:mine): provider, price, what it gives agents and what it needs |
sky plugins add [id] [--agent <id>] [--session <id>] [--source <source>] [--mcp-url <url> --token <token> --name <name>] [--task <id> --request <id>] [--json] | add or connect a plugin by id; when a person must sign in or pair, prints the address to open and the steps; --mcp-url adds a custom MCP server; --task and --request answer a task's connect request for an app with a once-only link the person opens without signing in |
sky plugins rm <id> [--connection <id>] [--disconnect] [--json] | remove a plugin or disconnect it by id; an app is disconnected only with --disconnect; a bare name removes that bundle's skills (one a session still holds is switched off) |
sky plugins off <id> --agent <id> / sky plugins on <id> --agent <id> | switch a plugin off (or back on) for one agent or, with --session <id>, one chat; the workspace and every other chat keep it |
sky plugins share <id> --workspace <slug> [--api-key <id> | --all-keys] [--connection <id>] | share your app connection with a workspace's chats, or let one of its keys (or every key) call through it |
sky plugins unshare <id> --workspace <slug> [--api-key <id> | --all-keys] [--connection <id>] | stop sharing it with that workspace's chats, or take back that key's (or every key's) access; an owner or admin may name a member's connection |
sky plugins shares <id> [--connection <id>] [--json] | where your connections of an app are shared: each workspace and API key, with the calls made through it |
sky plugins call <id> --url <https url> [--method <m>] [--header <name:value>]… [--body <text>] [--connection <id>] | with an API key: call the app's API through a connection its owner granted to this key; prints the app's {status, ok, body} |
| `sky plugins export <id> --format codex | claude |
| `sky plugins marketplace --format codex | claude |
sky setup plugins [--agent claude_code codex grok] [--dry-run] [--json] | install every plugin your workspace has switched on, and AgentSky's Mac plugins, in Claude Code, Codex and Grok on this computer, with each one's own command line; run it again to refresh them. Part of sky setup |
sky plugins answer <id> --agent <id> | choose which agent answers a chat app (--session <id> names one chat) |
sky plugins enable <name> / sky plugins disable <name> | switch a plugin on or off: its skills attach to new sessions or stop, and plugin sessions follow |
sky plugins run <name> <message> [--agent <id>] [--json] | start a plugin session: only that plugin's skills and MCP servers, connected apps limited to the ones it declared |
sky plugins policy <name> <recommended|default|blocked|none> [--source <source>] | workspace owners and admins: a plugin's policy; default installs it now, blocked stops installs |
sky plugins market list [--json] | every plugin the workspace's Claude Code marketplaces list, with its source, policy and install state |
sky plugins market add <source> / sky plugins market rm <source> | workspace owners and admins: list plugins from a folder holding .claude-plugin/marketplace.json, or stop |
sky plugins upload <dir> [--name <name>] [--json] | upload a directory with SKILL.md at its root as a new skill:<id> plugin (POST /plugins, multipart); sky plugins add skill:<id> makes it available to every new chat |
sky plugins revisions <id> [--save <dir> [--expected-latest-revision <id>]] [--rm <revisionId>] [--json] | a skill plugin's saved versions, newest first; --save uploads a new one, --rm deletes one |
sky plugins cat <id> <revisionId> <path> | print one file of a skill plugin's version, e.g. SKILL.md |
sky skills revisions <skillId> / sky skills cat <skillId> <revisionId> <path> / sky skills rm <skillId> | deprecated, still runs: sky plugins revisions skill:<id> / cat skill:<id> … / rm skill:<id> |
reflections
Skill and lesson changes a reviewer proposed after a finished, workspace-visible session. Nothing changes until a workspace owner or admin approves. A pending proposal is also a request in the task it came from, with Approve and Dismiss, addressed to the workspace's owner; answering it there is the same as sky reflections approve or reject.
| command | what it does |
|---|---|
sky reflections list [--status <status>] [--json] | the workspace's proposals (default: pending) |
sky reflections approve <id> | write the proposal through the skill store or memory store |
sky reflections reject <id> | decline the proposal; nothing is written |
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 |
design-system
A design system is an artifact whose files hold project/design-system.json: a brand book (project/README.md), tokens.json, components and assets, the file table a Claude Design System artifact keeps. Agents read its brand book before making slides, a design or a page.
| command | what it does |
|---|---|
sky design-system list | the workspace's design systems |
sky design-system show <id> [--readme] | its themes, tokens, components and assets, and any token it could not read; --readme prints the brand book |
sky design-system import <task> <folder> [--title "…"] | import a local folder (one holding project/, or project/ itself) into the task and publish it |
sky design-system tokens <id> <tokens.json> --base <version> [--note "…"] | save an edited tokens.json as the next version; refused when someone saved after --base |
sky design-system write <id> <path> [file] --base <version> [--restore <version>] [--note "…"] | save one of the system's editable files (such as project/README.md) from a local file as the next version, or put back the copy from --restore; refused when someone saved after --base |
sky artifact comments <id> [--text "…" --base <version> --reply <parent-id>] | read private artifact discussion, add feedback or reply in the viewed revision |
sky artifact comments <id> --resolve <root-id> --base <version> --state-version <version> | resolve a root thread; use --reopen instead to reopen; absent resolution metadata means state version 0 |
sky design-system comments <id> [--text "…" --base <version> --target color:ink] | read discussion or add feedback on the system, a color or a component; no agent starts |
library
Your artifact Library on agentsky.dev: the files and sites your agents saved or you uploaded (/v1/library/artifacts…). A task's artifacts on the platform are sky artifact.
| command | what it does |
|---|---|
sky library list [--search <text>] [--cursor <cursor>] [--json] | your Library, newest first |
sky library upload <path> [--workspace <key>] | save a file from this computer to your Library |
sky library show <id> | one artifact and its saved versions |
sky library delete <id> | delete your artifact with all its versions |
sky library share <id> | turn on its public link and print it |
sky library unshare <id> | turn off its public link |
sky library place <id> <workspace|me> | place it in a workspace, or take it back to you alone |
sky library download <id> <out> [--version <n>] | save one version's bytes to a file |
sky library links show --ref '<JSON>' [--workspace <slug>] | read any file's sharing, available members and current revision; creates nothing |
sky library links share --ref '<JSON>' [--workspace <slug>] [--workspace-access none|view|edit] [--member user:view|edit] [--remove-member user] [--revision <n>] | change only the requested grants; repeat member flags as needed; preserves public access |
sky library links publish --ref '<JSON>' [--workspace <slug>] [--disable] [--revision <n>] | create a public view-only link, or revoke only public access; preserves workspace and members |
sky library links revoke --ref '<JSON>' [--workspace <slug>] --revision <n> | revoke all sharing at an explicitly reviewed revision |
sky library links read --token <token> [--public] [--output <file>] | read the native shared document snapshot; public reads need no key; output streams original bytes with raw=1 |
sky library links save --token <token> --revision <source-revision> --file <UTF8> | save UTF-8 text through a live recipient edit grant and the original source writer |
sky library links save --token <token> --revision <source-revision> --data '<JSON>' | native HTML, Office, Word or restore: exactly one html, office, docx or restoreRevision (text also accepted), with optional requestId UUID; @file and - read JSON from disk or stdin |
The links commands use the same Library links API (GET/PUT/DELETE /library/links). Pass the source's exact reference as JSON: {"kind":"agent_prompt","agentId":"agent_…"} (the user-authored AGENTS.md only), {"kind":"file","fileId":"file_…","sessionId":"session_…"} (sessionId optional), {"kind":"task_file","taskId":"…","path":"report.md"}, {"kind":"memory_note","storeId":"…","memoryId":"…"}, {"kind":"skill_file","skillId":"…","path":"SKILL.md"}, {"kind":"artifact","artifactId":"…"}, or {"kind":"platform_artifact","artifactId":"…","path":"index.html"} (path optional). An uploaded meeting note uses its Drive file reference. --workspace names the audience workspace; these commands never move a file or send messages. For DesignSystem files, use the full native manifest path (the actual system root plus an editable_files path, or the native document reader's libraryRef). Omitting the platform path selects the entire artifact entry. Token readers reject ?path; a file link never selects a sibling. Editable DesignSystem files use their original versioned writer and republish the derived files. Only editable sources accept edit grants; public access is always view-only. A share or publish reads current state then saves only the requested changes. A conflict is reported without retrying over a newer revision. All link commands print the complete JSON receipt, including sharedUrl, publicUrl and revision. Legacy library share/unshare and artifact share keep their original URLs and version behavior.
Use the 43-character token from the end of /library/shared/<token> or /library/public/<token>. The default reader uses the caller's own key; --public chooses the anonymous view-only reader and sends no key. --output uses the same streaming file writer as other downloads and refuses HTTP errors before writing a file. The source revision from links read is an opaque string, distinct from the integer sharing-settings revision used by links revoke. Saving requires that exact source revision and exactly one native content/restore field; --file and --data are alternatives. Office and docx values are base64 native bytes. Save receipts name the version the original writer committed. A read-only grant returns 403; a stale revision returns 409 without retry. Public links have no save command or API writer.
todos
The checklist items (- [ ] text @who YYYY-MM-DD) of the Markdown documents in your Library and your workspaces, as Library › todos lists them (GET/PATCH /library/todos).
| Command | What it does |
|---|---|
sky todos list [--workspace] [--status open|done|all] [--due any|overdue|today|week|none] [--source <artifactId>] [--cursor <next_cursor>] [--today YYYY-MM-DD] [--json] | to-dos assigned to you or unassigned in your documents; --workspace lists every to-do you can read |
sky todos done <id> | tick it; its document saves a new version |
sky todos reopen <id> | untick it; its document saves a new version |
List reads do not repair or write the document's index. Follow next_cursor with the same filters and date, even when a filtered page has no items. Source counts cover documents on the page, not full Library totals; sources_partial and unavailable_source_count describe incomplete coverage. A changed resumed document returns 409 todo_page_changed: restart without the cursor. Item IDs are opaque locators, not access grants; tick/reopen reauthorize and edit the current saved document.
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 |
sky routine rm <id> | delete the routine: it never runs again; the sessions it started are kept |
sky routine runs [id] [--failed] [--limit n] | every fire attempt, newest first — of one routine or all — with the session it started or why it failed |
What starts a routine besides its schedule, and where its answers go. With no flag each command shows the current setting.
| command | what it does |
|---|---|
sky routine inbound-url <id> [--create|--rm] | a URL that starts a run when posted to, with no API token; --create prints it once and replaces any earlier one |
sky routine precheck <id> [https-url] [--rm] | scheduled fires run only when the content at the URL changed; skipped fires cost nothing |
sky routine result-email <id> [on|off] | email you each run's last answer (routines that start a new session per fire) |
sky routine chat-trigger <id> --connection <id> [--thread <id>] [--prefix "/report"] [--rm] | your own message in a connected chat starts a run; the text after the prefix is its input, and the answer is posted back there |
sky routine deliver-to <id> --connection <id> [--thread <id>] [--rm] | post each run's answer to a conversation in a connected chat |
link
A session someone shared with you by a guest link (/s/<token>). The link is the grant: any signed-in key may use it, turns bill the session's owner, and a view-only link can only be read (GET /links/<token>/events).
| command | what it does |
|---|---|
sky link send <link> <text...> [--idempotency-key key] | send a message through a guest link (URL or token); the same key never sends twice |
sky link stop <link> | stop the turn running on the session the link opens |
billing
Your own balance, auto top-up, usage and credit. A workspace's wallet is managed on the workspace.
| command | what it does |
|---|---|
sky billing show | balance, whether a card is saved, and auto top-up |
sky billing card | print the address of a card form; saving a card moves no money |
sky billing topup <10|20|50|100> [--request-id id] | buy credit with your saved card; the same request id never charges twice |
sky billing claim <link|code> | claim a credit invite link (agentsky.dev/i/<code>) for your own balance; claiming twice funds once |
sky billing auto-topup [--on|--off] [--threshold 5|10|20] [--amount 10|20|50|100] | show auto top-up, or change it; turning it on needs a saved card |
sky billing usage [--from day] [--to day] [--by day|kind|session|api_key] [--source session|api_key] [--key id] [--json] | what you spent over UTC days (--to excluded; default the last 30), across sessions and API keys |
sky billing export [same range flags] [--format csv|jsonl] [-o file] | every usage record in the range |
sky billing requests [--from day] [--to day] [--key id] [--cursor c] [--json] | one row per API request your developer API keys made, newest first; pass the printed cursor for the next page |
sky billing coding-plan show | whether you are on the coding plan, its monthly amount, and whether it renews |
sky billing coding-plan join <10|40> [--request-id id] | join with your saved card (charged now; API gateway calls are then billed at cost), or change your monthly amount from the next renewal |
sky billing coding-plan cancel | stop the plan renewing; the paid month stays |
sky billing referral-links list | your customer discount links, their use, and what referred customers earned you (accounts on a discount plan) |
sky billing referral-links create (--price 0.8 | --sku id=0.8 ...) [--email address] [--uses n] [--days n] | a discount link priced at no less than your own price; --email sends it to one customer and it redeems once |
sky billing referral-links disable <id> | stop a link being redeemed; customers already enrolled keep their price |
keys
Your own API keys (admin scope). Workspace keys belong to the workspace.
| command | what it does |
|---|---|
sky keys list | your keys, with prefix, status, scopes and last use |
sky keys create <name> [--scopes read,write,admin] [--workspace slug|personal] [--expires iso] | make a key; prints its secret once |
sky keys reveal <id> | print a key's secret again, where the key allows it |
sky keys revoke <id> / sky keys restore <id> | stop a key at once, or let a revoked key work again |
notes
Memory notes are the documents in the Library's memory stores; every save keeps the earlier version.
| command | what it does |
|---|---|
sky notes stores | the workspace's memory stores |
sky notes list <storeId> [folder/] | the notes in a store, optionally under a folder |
sky notes read <storeId> <noteId> | print one note |
sky notes save <storeId> <file> (--path /new/note.md | --note <noteId>) | write a note from a local file: a new one at --path, or a new version of --note |
memory and context
Your personal memory is what every session you start is told about you; context searches it, your past conversations and the workspace trace library.
| command | what it does |
|---|---|
sky memory list | your entries, numbered |
sky memory save <text…> / sky memory edit <n> <text…> / sky memory rm <n> / sky memory clear | change it; each write carries the version it read, so it never overwrites a change it did not see |
sky context search <words…> [--scope folder] [--limit n] [--cursor c] [--since iso] [--until iso] [--json] | the one search over everything you can open: plain words, "exact phrase" or /regex/ (every matching line), --scope a folder such as skills/review/, memory/, files/ or docs/; prints path:line: snippet and a sky context read line per hit |
sky context read '<ref>' [--offset n] | read a hit in full |
events
The work graph log: everything that happened in a task, a session or your own work, with every intermediate result kept whole. The same log takes events from any program of yours.
| command | what it does |
|---|---|
sky events search [--task id] [--session id] [--object type:id] [--kind k] [--from iso] [--to iso] [--cursor c] [--limit n] [--json] | events in time order; --object sha256:<hex> finds every event that touched those exact bytes, in any thread |
| `sky events digest [--period day | hour] [--from iso] [--to iso] [--limit n] [--json]` |
sky events show <id> | one event in full |
sky events body <id> [--part role] [--text] [--out file] | an event's stored body, whole: a connector reply, a context result, a request or a large payload |
sky events push [file] | write events from your own program (a JSON file or stdin with {events: [...]}); idempotent per idempotency_key |
webhook
Your HTTPS endpoints for platform events, each signed with a whsec_ secret.
| command | what it does |
|---|---|
sky webhook list | endpoints, their events and status |
sky webhook create <url> --event <type…> | register an endpoint (for example --event goal.completed routine_run.failed); prints its secret once |
sky webhook enable <id> | re-enable an endpoint disabled after failed deliveries |
sky webhook rm <id> | delete it |
hook-rule
Workspace hook rules run a webhook or block at platform-controlled points: session.start, tool.call, spend, and turn.end. Rules are evaluated in order; the first matching rule decides. See PUT /v1/hook_rules in the API reference for the rule schema.
| command | what it does |
|---|---|
sky hook-rule list [--workspace <slug>] [--json] | the workspace's top-level hook rules (no --workspace) or the workspace-level hooks for a specific workspace |
sky hook-rule set [--workspace <slug>] [--rules <json-array>] | replace the entire ordered list; reads JSON from stdin when --rules is omitted |
vendor
External vendor accounts: third-party API keys and agent logins your agents use (such as OpenAI, Anthropic, or other model providers connected as accounts).
| command | what it does |
|---|---|
sky vendor list [--json] | the workspace's vendor accounts, with status and last use |
sky vendor add <vendor> [--label <name>] [--credential <value>] | connect a vendor account; prompts for the credential when --credential is omitted |
sky vendor rm <id> | disconnect a vendor account |
sky vendor usage <id> [--json] | the agents and tasks that used this account |
browser-profile
Your browser: the sites your agents stay signed in to between sessions. It is yours in every workspace; share it with one member or the whole workspace, for every site or only some. Needs your own ast_ key; a workspace key lists only what is shared with the whole workspace.
| command | what it does |
|---|---|
sky browser-profile list [--json] | your browser, whom you shared it with, and the browsers shared with you here |
sky browser-profile sites [--json] | the sites your browser is signed in to |
sky browser-profile import [--file <path>] | import a Playwright storage-state JSON file into your browser; reads stdin when --file is omitted |
sky browser-profile remove-site <site> | sign your browser out of a site everywhere (the agent will need to sign in again) |
sky browser-profile share [--member <user id>] [--sites <a,b>] | share your browser with one member, or everyone here; every site unless --sites |
sky browser-profile unshare <share id> | stop a share; it ends from the grantee's next turn |
mac
Your Macs, through the This Mac relay: what each one lends to agents now, and asking one to lend a folder, a browser window or its screen. The person answers on the Mac (the folder picker, or Allow / Deny); the CLI only asks and waits. Needs your own ast_ key: a workspace key cannot see or ask for what a person lends.
| command | what it does |
|---|---|
sky mac tools <mount> [--workspace slug] [--personal-workspace] | list authorized Mac host operations and their exact argument schemas |
sky mac call <mount> <tool> [--arguments json] [--request-id id] [--workspace slug] [--personal-workspace] | invoke an advertised operation; reuse the printed request id when retrying the same call; key, workspace, task scope and macOS permissions still apply |
| `sky mac plugin-mcp <meetings | |
sky mac list [--json] | your Macs: online or not, what each can lend (and why not the screen), and the folders, browser windows and screens lent now |
sky mac ask <machine> <folder|browser|screen|host> --reason <text> [--no-wait] [--json] | ask a Mac to lend one (host: its local Claude Code and Codex chats, call notes, uploads, saves to Downloads and local git, every change confirmed on the Mac); prints the mcp_url a session attaches once granted, and waits up to four minutes for the answer (exit 1 when it is denied, unavailable or expired) |
sky mac ask-status <id> [--wait <seconds>] [--json] | where an ask stands: pending, asking, granted, denied, unavailable or expired |
sky mac take-back <mount> | end a folder, browser window, screen or apps and files lent from a Mac |
notifications
Email and browser push notification preferences for tasks.
| command | what it does |
|---|---|
sky notifications get [--json] | the current email and push preferences |
sky notifications unsubscribe-marketing | stop AgentSky marketing email to your address; login and account email continue |
sky notifications set [--email-needs-you true|false] [--email-done true|false] [--push-needs-you true|false] [--push-done true|false] | update one or more settings |
help
Search the AgentSky help center or read an article.
| command | what it does |
|---|---|
sky help search <words…> [--top n] [--json] | full-text search across help articles (returns up to 20) |
sky help get <slug> [--json] | read a full help article by its slug |
api
Every operation in the API reference from the terminal, with your logged-in key: the same route, checks and answer as any other client (like gh api). The named commands above are the everyday interface; sky api reaches everything else a person can do on agentsky.dev or in the Mac app.
| command | what it does |
|---|---|
sky api search <words…> | list the operations whose method, path or summary contain every word |
sky api <METHOD> <path> [-q key=value]… [-d json|@file|-] [--workspace slug] [--idempotency-key k] [-o file] | send one request, e.g. sky api PATCH /threads/thr_123 -d '{"title":"Q3 plan"}'; prints the JSON answer, exits 1 on an error answer; -o saves a download |
channel
Chat surfaces (Slack, Telegram, Discord, WhatsApp, iMessage, email, Teams, X, Lark, Google Chat, LINE) routed to a session. Chat apps are plugins now (chat:<platform>): connect one with sky plugins add, choose who answers with sky plugins answer, disconnect with sky plugins rm; the deprecated commands below still run them. Building your own bot on channel webhooks, deliveries and reactions is on the API (/channels/… in /docs/api).
| command | what it does |
|---|---|
sky channel list | your connections, their status and the session each routes to |
sky channel connect <platform> [--session sess_…] [--wait] | deprecated, still runs: sky plugins add chat:<platform> --session sess_…; with --webhook <id> it still routes to a channel webhook on its own route; --app <id> runs it on your own bot or number, --label names it |
sky channel bind <connectionId> --session sess_… | deprecated, still runs: sky plugins answer chat:<platform> --session sess_… --connection <id>; --webhook <id> stays on its own route |
sky channel send <threadId> <text…> | post a markdown message into a connected thread |
sky channel history <threadId> [--limit n] [--cursor token] | read one authorized conversation history page as JSON; start with the newest page, then pass next_cursor to retrieve older messages |
sky channel disconnect <connectionId> | deprecated, still runs: sky plugins rm chat:<platform> --connection <id> |
sky channel apps | your own bots and numbers registered as channel apps |
sky channel identities | chat identities whose messages run as you |
sky channel unlink <identityId> | unlink one; that person's messages stop running as you |
History reads do not start a turn or download files. history_source distinguishes provider history from retained SDK messages; unsupported channels return 501. Cursors expire after an hour and stay bound to the same caller, thread, installation and page size. Repeating a cursor safely retries the same page.
connector
Deprecated: apps are plugins now; use sky plugins (sky plugins list --view yours --source app, add app:<app>, share, shares, call). Every command below still runs, and those with a plugin route print one line on stderr naming the sky plugins command they now run. Authorization runs in your browser; sky listens on a loopback port for its return and records the account.
| command | what it does |
|---|---|
sky connector apps [query] | deprecated, still runs: sky plugins list --view discover --source app --q <query> (--limit n) |
sky connector list | deprecated, still runs: sky plugins list --view yours --source app --include connections |
sky connector connect <app> | deprecated, still runs: sky plugins add app:<app> (opens the sign-in unless --no-open); --universe <slug> still connects it for the workspace itself (owner or admin) |
sky connector disconnect <connectionId> | deprecated, still runs: sky plugins rm app:<app> --connection <id> --disconnect |
sky connector repos | repositories your GitHub connection can reach |
sky connector workspace [slug] | deprecated, still runs: sky plugins list --view yours --source app in that workspace |
sky connector share <connectionId> [--universe <slug>] | deprecated, still runs: sky plugins share app:<app> --workspace <slug> --connection <id> |
sky connector unshare <connectionId> [--universe <slug>] | deprecated, still runs: sky plugins unshare app:<app> --workspace <slug> --connection <id> |
sky connector shared | deprecated, still runs: sky plugins list --view yours --source app --include shared |
sky connector grant <connectionId> [--key <id>] [--universe <slug>] | deprecated, still runs: sky plugins share app:<app> --workspace <slug> --api-key <id> (or --all-keys) |
sky connector revoke <connectionId> [--key <id>] [--universe <slug>] | deprecated, still runs: sky plugins unshare app:<app> --workspace <slug> --api-key <id> (or --all-keys) |
sky connector grants <connectionId> | deprecated, still runs: sky plugins shares app:<app> --connection <id> |
sky connector granted | deprecated, still runs: sky plugins list --view yours --source app --include granted |
vault
Credentials a session is granted when it starts (vault_ids on POST /sessions). A value is read from stdin when piped, otherwise from a prompt that does not echo; it is never printed back.
| command | what it does |
|---|---|
sky vault list | the workspace's vaults |
sky vault create <name> | create one; prints its vlt_ id |
sky vault show <vaultId> | its secrets — names, kinds, hosts, status; never values |
sky vault rm <vaultId> [-y] | delete it and every secret in it |
sky vault move <intoVaultId> --from <vaultId…> [--dry-run] | move the secrets of other vaults into this one |
sky vault secret add <vaultId> <NAME> --host <host…> | add an environment variable sent only to those hosts (--header <name>, --template 'Bearer {secret}'); with --mcp <url>, store a bearer token for that MCP server instead |
sky vault secret rotate <vaultId> <secretId> | replace its value in place, running sessions keep working (--host re-scopes, --keep-value changes only the hosts) |
sky vault secret rm <vaultId> <secretId> | delete a secret |
sky vault secret validate <vaultId> <secretId> | check that an MCP OAuth grant still works |
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) |
sky workspace delete <slug> [-y] | permanently delete a workspace you own (alias of sky universe delete) |
sky workspace rename <slug> <name…> | rename a workspace you own; the slug stays (alias of sky universe rename) |
sky workspace context | what every session in the workspace loads at start (AGENTS.md, MEMORY.md, the indexes, your member page) with sizes and limits |
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 |
sky universe delete <slug> [-y] | permanently delete a workspace you own and everything in it: prints what will go, then asks you to type the slug (-y skips that). Its sessions are stopped, its wallet's credit returns to you; not your default workspace |
sky universe rename <slug> <name…> | rename a workspace you own (PATCH /universes/{slug}); the slug stays |
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
$ 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_TOKENcompare
Run a task on two or more agents side-by-side and record your decision. A comparison is a playground with more than one column; each column is a session.
| command | what it does |
|---|---|
sky compare create --agent <type> --llm <model> --task "…" --compare <type:model>… | create a comparison: one primary agent and one or more compare agents, all starting the same task; prints the comparison id and column session ids |
sky compare list [--archived] [--json] | workspace comparisons, newest first |
sky compare show <id> [--json] | one comparison: columns, arena status, and vote result if revealed |
sky compare pick <id> (--winner <columnId> | --tie | --both-bad) [--json] | record your winner pick; --tie or --both-bad for draws; prints the revealed agents once the vote is recorded |
thread
Conversations as the web rail shows them: one agent, or several side by side. Every command calls /v1/threads…; an agent column is named by the column id sky thread show prints.
| command | what it does |
|---|---|
sky thread list [--archived|--all] [--json] | workspace threads, newest first |
sky thread start "<text>" --agent <type> [--llm <model>] [--effort <level>] [--vs <type:model>…] [--saved-agent <id>] [--workspace <slug>] [--plan] [--json] | start a thread and send its first message, as the web composer does |
sky thread show <id> [--json] | one thread: every agent and the session it runs in |
sky thread rename <id> "<title>" | rename a thread |
sky thread pin <id> | pin a thread to the top of the rail |
sky thread unpin <id> | unpin a thread |
sky thread archive <id> | put a thread away |
sky thread unarchive <id> | bring an archived thread back |
sky thread mark-read <id> | mark a thread read |
sky thread mark-unread <id> | mark a thread unread |
sky thread delete <id> | delete a thread with its sessions |
sky thread send <id> "<text>" [--agent <columnId>…] [--json] | send one message to every agent, or only the ones named |
sky thread add-agent <id> --agent <type> [--llm <model>] [--effort <level>] | add an agent to the thread |
sky thread remove-agent <id> <columnId> | take one agent out; its session is left as it is |
sky thread stop <id> [--agent <columnId>] | stop what the thread's agents are doing |
sky thread fork <id> [--agent <columnId>] [--at <messageId>] [--to <type:model>] | continue one agent's conversation in a thread of its own |
sky thread model <id> [--agent <columnId>] [--llm <model>] [--effort <level>|default] | change the model or thinking level one agent runs on |
sky thread search "<query>" [--archived|--all] [--cursor <cursor>] | search the words of your conversations |
sky thread options | what a new thread can start on: agents, models, thinking levels and grantable tools |
sky thread join <sessionId> | open a teammate's thread, or one shared with you |
project
The GitHub repositories a new thread can start on (/v1/projects).
| command | what it does |
|---|---|
sky project list [--json] | repositories a new thread can start on, the last one chosen starred |
sky project use [owner/name] [--branch <branch>] | remember a repository for your next new thread, or none when omitted |
session feedback
Thumbs-up/down reactions on individual messages.
| command | what it does |
|---|---|
sky session feedback <id> [--json] | read thumbs-up/down feedback recorded on this session's messages |
session side-chat
Ask a question about a session's transcript, answered outside the main conversation.
| command | what it does |
|---|---|
sky session side-chat <id> --question "…" --transcript "…" [--quote "…"] [--json] | ask a side question; the answer is returned directly, never sent to the agent |
session code-review
Run the code-review plane on a diff or file, using the session's context.
| command | what it does |
|---|---|
sky session code-review <id> --diff "…" [--filename <name>] [--json] | review a diff or file; returns a review summary and a list of findings |
session snapshot
Read or revoke the public share link for a session.
| command | what it does |
|---|---|
sky session snapshot <id> --thread <threadId> [--revoke] [--json] | read the snapshot link; --revoke clears it |