# CLI for coding agents

> How Claude Code, Codex or Cursor use the Ghosty CLI for you — agent-driven login, JSON output, exit codes and the ghosty-agent skill.

URL: https://www.ghosty.studio/en/docs/cli/coding-agents

The CLI is built for your coding agent to drive. It costs little context (the agent learns it from `--help`), composes with other tools, and its output is stable.

## The recipe

1. Install the skill that teaches your agent to use Ghosty:
   ```bash
   npx skills add https://www.ghosty.studio
   ```
2. Ask for what you want in plain words: "change my sales agent's prompt so it quotes in dollars, and test it".

The `ghosty-agent` skill tells it which commands to use and in what order; the CLI does the work.

## The agent drives the login

You don't have to open a terminal:

1. The agent runs `ghosty login --json`.
2. The first line out is `{"event":"login_url","url":"…"}`. The agent hands you that link in the chat.
3. You open the link and sign in. If you already have a session on ghosty.studio, opening it is enough.
4. The CLI receives the session, prints `{"event":"logged_in","email":"…"}` and the agent carries on.

The session is stored on your computer and renews itself. Later commands ask for nothing.

:::tabs
```bash tab=What the agent runs
ghosty login --json
# {"event":"login_url","url":"https://www.ghosty.studio/oauth2/authorize?…"}
# … the person opens the link …
# {"event":"logged_in","email":"you@example.com"}
```
:::

## Machine output

With `--json`, stdout carries **only JSON** and notices go to stderr, so the agent can read the result without cleaning it up.

```bash
ghosty agents ls --json
# [{"id":"cm…","name":"Sales","engine":"claude-worker","source":"gs","lastActivity":"2026-09-25T…"}]
```

`ghosty chat --json` emits one line per event: `chunk`, `tool`, and finally `done` with the full text and token usage.

## Exit codes

| Code | Meaning | What the agent does |
|---|---|---|
| `0` | OK | Carries on. |
| `1` | API error | Reads the message; doesn't retry blindly. |
| `2` | Usage error | Checks `ghosty <command> --help`. |
| `3` | Not signed in | Runs `ghosty login --json` and hands you the link. |

Errors with `--json` look like: `{"error":"Not logged in.","code":3,"hint":"Run: ghosty login"}`.

## The agent runs on another machine

If the agent works in a box, in CI or over SSH (away from your browser), `ghosty login` notices and uses a **device code**:

```bash
ghosty login --json
# {"event":"login_url","url":"https://www.ghosty.studio/activar?code=WDJB-MJHT","code":"WDJB-MJHT","method":"device"}
```

The agent hands you the link; you open it on your phone or computer, **check that the code matches** and authorize. The CLI picks it up and carries on. To force it from any machine: `ghosty login --device`.

Only authorize codes you or your agent just asked for: if someone else sends you an `/activar` link, reject it.

## No browser: agent token

For CI or a remote machine with no browser, use the agent's token (`gat_…`, generated on the agent's page → **Generate token**):

```bash
export GHOSTY_TOKEN=gat_…
ghosty agents get <id>
ghosty agents set <id> --prompt-file PROMPT.md
ghosty try <id> "ping"
```

That token reaches **only its** agent. To list agents or use `chat`, sign in with `ghosty login`.