Command reference

The full skydive command surface. Every command also answers --help, and all commands accept the global flags --json, --quiet, and --api-url.

chat

Open the interactive chat TUI, or send a one-shot prompt with -p.

Flag	Effect
`-p, --print [prompt]`	Non-interactive: send one prompt, print the reply, exit. Reads stdin when given no value.
`--agent <ref>`	Target agent by id, slug, or name. Without `-p`, skips the agent picker.
`--conversation <id>`	With `-p`: continue an existing conversation.
`--new`	Start a fresh conversation instead of resuming the last one.
`--share-machine`	Share this machine with the agent over Portal.
`--theme <id>`	Pin a colorscheme. Also settable via `SKYDIVE_THEME`.
`--no-notify`	Disable desktop notifications.

auth

Manage authentication.

Subcommand	What it does
`auth login`	Store an API key (`--api-key sky_live_...`, or paste at the prompt)
`auth login --web`	Sign in for chat via the browser device flow
`auth status`	Show current authentication state
`auth logout`	Clear stored credentials (API key and chat session)

agents

Subcommand	What it does
`agents list`	List agents in the active workspace (`--limit`, `--scope mine\|org`)
`agents get <id>`	Get agent details
`agents create`	Create a new agent (`--name`, `--model`)

conversations

Subcommand	What it does
`conversations list`	List an agent’s conversations (`--agent`, `--limit`)
`conversations show <id>`	Print a conversation transcript (`--recap` for the summary instead)

messages

Subcommand	What it does
`messages get <message-id>`	Re-fetch an agent reply by id (the `messageId` from a prior `chat -p --json`)

workspace

Subcommand	What it does
`workspace list`	List workspaces on your account
`workspace switch [workspace]`	Switch the active workspace by slug, name, or id. No argument picks interactively.

keys

API keys for an agent. All subcommands take --agent-id <id>.

Subcommand	What it does
`keys list`	List API keys
`keys create <name>`	Create a key
`keys revoke <id>`	Revoke a key

secrets

An agent’s secrets. All subcommands take --agent-id <id>. Values are never shown after they are set.

Subcommand	What it does
`secrets list`	List secret names
`secrets set <key> [value]`	Set a secret. Reads the value from stdin when omitted.
`secrets rm <key>`	Remove a secret

portal

Share this machine with agents. See Reaching your computer.

Subcommand	What it does
`portal open`	Open Portal headless, in the foreground (`--agent` to grant one immediately, `--cwd` to set the working directory, `ctrl+c` to close)
`portal grant`	Grant an agent access to this machine
`portal revoke`	Remove an agent’s access
`portal status`	Show machines, connection state, and granted agents

fs

Work with files on an agent’s sandbox from your own machine.

Subcommand	What it does
`fs edit <path>`	Open a remote file in your local editor (`$VISUAL`, then `$EDITOR`, then `vi`), and write your changes back when you save and close. A path that doesn’t exist yet is created on save. Pass `--editor <cmd>` to override.

skydive fs edit --agent grace /tmp/notes.md
EDITOR=nano skydive fs edit ~/.self/soul.md

File access requires the same edit permission as skydive sandbox. The agent name or id can be provided with --agent.

sandbox

Open a live terminal in an agent’s sandbox, or run a one-shot command there.

Usage	What it does
`sandbox`	Open an interactive sandbox terminal (needs a TTY)
`sandbox -- <cmd>`	Run one command in the sandbox and print its output

import

Import your Claude Code, Cursor, or OpenCode setup into an agent. Opens a machine-shared chat so the agent can read your local config.

update

Update the CLI to the latest release in place.

Flag	Effect
`--check`	Only report whether an update is available, don’t install
`--channel <name>`	Update from a specific release channel
`--force`	Reinstall even when already current

config

View and change CLI preferences without editing config.json by hand.

skydive config                       # list all preferences with their current values
skydive config get updateCheck       # print one key
skydive config set updateCheck false # change a preference
skydive config unset updateCheck     # revert to the built-in default
skydive config path                  # print the config.json location

Available preferences:

Key	Type	Default	Effect
`updateCheck`	boolean	`true`	Check for CLI updates on startup
`shareMachineDefault`	boolean	`false`	Grant the agent Portal access automatically when you open chat

config only exposes safe, hand-editable preferences. It cannot read or write credentials or flow-managed state. The file itself lives at the platform-conventional path:

Platform	Location
macOS	`~/Library/Preferences/skydive/config.json`
Linux	`~/.config/skydive/config.json` (or `$XDG_CONFIG_HOME/skydive/`)
Windows	`%APPDATA%\skydive\config.json`

skydive config path prints the resolved path on your machine.

logs

The CLI records local diagnostics by default. It keeps the latest 20 sessions. Nothing uploads automatically. If you run into a bug or unexpected behavior, export the latest session. The CLI can open a prefilled issue in the public Skydive CLI issue tracker, or you can open the tracker and file the issue yourself. Attach the exported archive to help us diagnose what happened.

Subcommand	What it does
`logs list`	List recent diagnostic sessions
`logs path [session]`	Print a session directory. Defaults to the latest session.
`logs export [session]`	Create a `.tar.gz` archive and offer to open a prefilled GitHub issue. Defaults to the latest session. Use `--output` to choose the archive path.

Automatic logs include request timing, TUI state changes, render performance, and process metadata. Command values and URL query values are removed.

skydive logs
skydive logs path
skydive logs export

completion

Shell completions for bash, zsh, and fish.

Subcommand	What it does
`completion install [shell]`	Install completions into your shell’s startup file (auto-detects `$SHELL`)
`completion [shell]`	Print the completion script without installing

Environment variables

Variable	Effect
`SKYDIVE_API_KEY`	Management API key, instead of `auth login`
`SKYDIVE_SESSION_TOKEN`	Chat session for non-interactive use
`SKYDIVE_THEME`	Pin a TUI colorscheme
`SKYDIVE_CHANNEL`	Release channel for the install script (`canary` for beta builds)
`SKYDIVE_API_URL`	Override the API base URL
`SKYDIVE_APP_URL`	Override the app base URL
`SKYDIVE_BUN_PATH`	Point chat at an existing Bun binary
`SKYDIVE_PROFILE`	Write a full profile to the working directory (`1`) or a specific path. Full profiles add CPU data. Set to `0` to disable all session diagnostics.

​chat

​auth

​agents

​conversations

​messages

​workspace

​keys

​secrets

​portal

​fs

​sandbox

​import

​update

​config

​logs

​completion

​Environment variables