# Referencia de comandos

> Todos los comandos del CLI de Ghosty con ejemplos, opciones globales y códigos de salida.

URL: https://www.ghosty.studio/docs/cli/comandos

Todos aceptan `--json` y `--help`. `<id>` es el id de un agente (sale en `ghosty agents ls`).

## Sesión

| Comando | Qué hace |
|---|---|
| `ghosty login` | Abre el navegador y entra con tu cuenta (OAuth2). |
| `ghosty login --device` | Entra desde otro dispositivo con liga + código (automático por SSH o CI). |
| `ghosty logout` | Cierra la sesión y la revoca en el servidor. |
| `ghosty whoami` | Tu correo y tu plan. |

## Agentes

```bash
ghosty agents ls
ghosty agents get <id>                         # configuración completa
ghosty agents get <id> --fields name,model,prompt
ghosty agents set <id> --prompt-file PROMPT.md # identidad / instrucciones
ghosty agents set <id> --name "Ventas" --model claude-sonnet-5
ghosty agents restart <id>                     # carga archivos, skills y MCP nuevos
```

`set` cambia sólo lo que le pases. El prompt y el modelo se aplican desde el siguiente turno.

## Configurar un agente

Archivos, skills y MCP viven en la **máquina del agente**. Si su motor no tiene máquina propia, el CLI te lo dice; nombre, modelo y prompt sí se cambian con `agents set`.

```bash
# Archivos (hasta 10 MB cada uno)
ghosty files ls <id>
ghosty files put <id> precios.md --file ./precios.md
cat notas.txt | ghosty files put <id> notas.txt
ghosty files get <id> precios.md --out ./copia.md
ghosty files rm <id> precios.md

# Skills: del catálogo por su nombre, o una propia con --file
ghosty skills ls <id>
ghosty skills add <id> grill-me
ghosty skills add <id> mi-skill --file ./SKILL.md
ghosty skills rm <id> mi-skill

# Servidores MCP: `set` REEMPLAZA la lista completa
ghosty mcp get <id> > servers.json
ghosty mcp set <id> --file servers.json

ghosty agents restart <id>
```

## Platicar con un agente

```bash
# Un turno de prueba: espera la respuesta completa (hasta 3 min)
ghosty try <id> "¿qué horarios tienen?"
ghosty try <id> "hola" --whatsapp        # como le llegaría por WhatsApp
ghosty try <id> --reset                  # olvida la sesión de prueba

# Conversación en streaming
ghosty chat <id> "resume el último correo"
ghosty chat <id>                         # modo interactivo; Ctrl-C cancela el turno, Ctrl-D sale
ghosty chat <id> "sigue" --conversation <conversation-id>
ghosty conversations ls <id>
```

`try` es para probar configuración; `chat` usa las conversaciones reales del agente, las mismas que ves en el panel y en la app.

## Tu cuenta

```bash
ghosty me files ls --kind document
ghosty me files upload ./contrato.pdf
ghosty me files rm <file-id>
ghosty docs                              # abre esta documentación
```

## Opciones globales

| Opción | Qué hace |
|---|---|
| `--json` | Salida para máquinas: stdout lleva sólo JSON. Avisos y progreso van a stderr. |
| `--token <token>` | Usa ese token en vez de la sesión. También por la variable `GHOSTY_TOKEN`. |
| `-h`, `--help` | Ayuda. |
| `-v`, `--version` | Versión. |

Un token de agente (`gat_…`, se genera en la ficha del agente) sólo alcanza a **ese** agente: sirve para `agents get/set/restart`, `files`, `skills`, `mcp` y `try`, pero no para listar agentes ni para `chat`.

## Códigos de salida

| Código | Significa |
|---|---|
| `0` | Bien. |
| `1` | Error de la API (el mensaje dice cuál). |
| `2` | Uso incorrecto: comando u opción que no existe, falta un argumento. |
| `3` | Sin sesión. Corre `ghosty login`. |