Documentation
CLI

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.

Updated 2026-09-25

Open in Claude ↗Open in ChatGPT ↗?
Ask your coding agent

Install the Ghosty skill (npx skills add https://www.ghosty.studio) and use the CLI (npx -y @ghostystudio/cli) to configure my agent per https://www.ghosty.studio/en/docs/cli/coding-agents.md.

Paste it in Claude Code, Cursor or Codex with the ghosty-agent skill installed.

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.

bash
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

CodeMeaningWhat the agent does
0OKCarries on.
1API errorReads the message; doesn't retry blindly.
2Usage errorChecks ghosty <command> --help.
3Not signed inRuns 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.mdghosty try <id> "ping"

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

← Previous
Command reference
Next →
Authentication