CLI

Command reference

Every Ghosty CLI command with examples, global options and exit codes.

Updated 2026-09-25

Every command accepts --json and --help. <id> is an agent id (shown by ghosty agents ls).

Session

Command	What it does
`ghosty login`	Opens the browser and signs you in (OAuth2).
`ghosty login --device`	Sign in from another device with a link + code (automatic over SSH or CI).
`ghosty logout`	Signs out and revokes the session on the server.
`ghosty whoami`	Your email and plan.

Agents

bash

ghosty agents lsghosty agents get <id>                         # full configghosty agents get <id> --fields name,model,promptghosty agents set <id> --prompt-file PROMPT.md # identity / instructionsghosty agents set <id> --name "Sales" --model claude-sonnet-5ghosty agents restart <id>                     # loads new files, skills and MCP

ghosty agents lsghosty agents get <id>                         # full configghosty agents get <id> --fields name,model,promptghosty agents set <id> --prompt-file PROMPT.md # identity / instructionsghosty agents set <id> --name "Sales" --model claude-sonnet-5ghosty agents restart <id>                     # loads new files, skills and MCP

set changes only what you pass. Prompt and model apply from the next turn.

Configure an agent

Files, skills and MCP live in the agent's machine. If its engine has no machine of its own, the CLI tells you so; name, model and prompt can still be changed with agents set.

bash

# Files (up to 10 MB each)ghosty files ls <id>ghosty files put <id> prices.md --file ./prices.mdcat notes.txt | ghosty files put <id> notes.txtghosty files get <id> prices.md --out ./copy.mdghosty files rm <id> prices.md
# Skills: from the catalog by name, or your own with --fileghosty skills ls <id>ghosty skills add <id> grill-meghosty skills add <id> my-skill --file ./SKILL.mdghosty skills rm <id> my-skill
# MCP servers: `set` REPLACES the whole listghosty mcp get <id> > servers.jsonghosty mcp set <id> --file servers.json
ghosty agents restart <id>

# Files (up to 10 MB each)ghosty files ls <id>ghosty files put <id> prices.md --file ./prices.mdcat notes.txt | ghosty files put <id> notes.txtghosty files get <id> prices.md --out ./copy.mdghosty files rm <id> prices.md
# Skills: from the catalog by name, or your own with --fileghosty skills ls <id>ghosty skills add <id> grill-meghosty skills add <id> my-skill --file ./SKILL.mdghosty skills rm <id> my-skill
# MCP servers: `set` REPLACES the whole listghosty mcp get <id> > servers.jsonghosty mcp set <id> --file servers.json
ghosty agents restart <id>

Talk to an agent

bash

# One test turn: waits for the full answer (up to 3 min)ghosty try <id> "what are your opening hours?"ghosty try <id> "hi" --whatsapp          # as it would arrive over WhatsAppghosty try <id> --reset                  # forget the test session
# Streaming conversationghosty chat <id> "summarize the last email"ghosty chat <id>                         # interactive; Ctrl-C cancels the turn, Ctrl-D exitsghosty chat <id> "go on" --conversation <conversation-id>ghosty conversations ls <id>

# One test turn: waits for the full answer (up to 3 min)ghosty try <id> "what are your opening hours?"ghosty try <id> "hi" --whatsapp          # as it would arrive over WhatsAppghosty try <id> --reset                  # forget the test session
# Streaming conversationghosty chat <id> "summarize the last email"ghosty chat <id>                         # interactive; Ctrl-C cancels the turn, Ctrl-D exitsghosty chat <id> "go on" --conversation <conversation-id>ghosty conversations ls <id>

try is for testing configuration; chat uses the agent's real conversations, the same ones you see in the dashboard and the app.

Your account

bash

ghosty me files ls --kind documentghosty me files upload ./contract.pdfghosty me files rm <file-id>ghosty docs                              # opens these docs

ghosty me files ls --kind documentghosty me files upload ./contract.pdfghosty me files rm <file-id>ghosty docs                              # opens these docs

Global options

Option	What it does
`--json`	Machine output: stdout carries JSON only. Notices and progress go to stderr.
`--token <token>`	Use this token instead of the session. Also via the `GHOSTY_TOKEN` variable.
`-h`, `--help`	Help.
`-v`, `--version`	Version.

An agent token (gat_…, generated on the agent's page) reaches only that agent: it works for agents get/set/restart, files, skills, mcp and try, but not for listing agents or chat.

Exit codes

Code	Meaning
`0`	OK.
`1`	API error (the message says which).
`2`	Usage error: unknown command or option, missing argument.
`3`	Not signed in. Run `ghosty login`.

← Previous

CLI — Ghosty from your terminal

CLI for coding agents