# Command reference

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

URL: https://www.ghosty.studio/en/docs/cli/commands

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 ls
ghosty agents get <id>                         # full config
ghosty agents get <id> --fields name,model,prompt
ghosty agents set <id> --prompt-file PROMPT.md # identity / instructions
ghosty agents set <id> --name "Sales" --model claude-sonnet-5
ghosty 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.md
cat notes.txt | ghosty files put <id> notes.txt
ghosty files get <id> prices.md --out ./copy.md
ghosty files rm <id> prices.md

# Skills: from the catalog by name, or your own with --file
ghosty skills ls <id>
ghosty skills add <id> grill-me
ghosty skills add <id> my-skill --file ./SKILL.md
ghosty skills rm <id> my-skill

# MCP servers: `set` REPLACES the whole list
ghosty mcp get <id> > servers.json
ghosty 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 WhatsApp
ghosty try <id> --reset                  # forget the test session

# Streaming conversation
ghosty chat <id> "summarize the last email"
ghosty chat <id>                         # interactive; Ctrl-C cancels the turn, Ctrl-D exits
ghosty 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 document
ghosty me files upload ./contract.pdf
ghosty 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`. |