> ## Documentation Index
> Fetch the complete documentation index at: https://vespin.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Work with tasks, agents, and your Inbox from a terminal

`vespin` is Vespin's command-line tool. It does what the app does from a shell: create tasks, start and follow agents, check out their branches, and answer your Inbox. It prints JSON for scripts and for coding agents that call it.

## Install

On a Mac with the app, open **Settings › Vespin CLI** and click **Install**. Anywhere else, use one of these:

```sh theme={null}
# Node 20 or later
npm i -g vespin

# Bundles its own Node; macOS (Apple silicon) or Linux
curl -fsSL https://vespin.dev/install.sh | sh -s cli

# Run once without installing
npx vespin --help
```

`vespin update` updates a curl install in place. For an npm install it prints the command to run.

## Sign in

```sh theme={null}
vespin login
```

It opens your browser. On a machine with no browser, such as one you reach over SSH, run `vespin login --no-browser` and paste back the address your browser lands on. The CLI appears under **Connected** in Settings › Vespin MCP, where you can disconnect it.

If you're in more than one workspace, set the default with `vespin workspace use <slug>`, or pass `--workspace <slug>` to any command.

## Work from a repository

Run these inside a checkout. The CLI reads the repository from the folder.

```sh theme={null}
# Create a task here, with an agent on it
echo "Fix the login redirect" | vespin task create "Login redirect" --prompt -

# Stream the agent's turn, or block until it ends
vespin agent logs <id> --follow
vespin agent wait <id>

# Fetch its branch, as gh pr checkout does
vespin agent checkout <id>

# Message the agent
vespin agent send <id> "Also cover the signup page"
```

## Answer your Inbox

```sh theme={null}
# Open threads, unread marked ●
vespin inbox list

# A thread and its open ask
vespin inbox view <id>

# Pick an option, or done for a to-do
vespin inbox answer <id> <option>

# Write on the thread
vespin inbox reply <id> "Use the staging database"
```

## Scripts and coding agents

Output is a table at a terminal, and JSON when piped or with `--json`. `--quiet` prints only ids. The exit code says how a command ended:

| Code | Meaning |
| - | - |
| 0 | Done |
| 1 | Refused |
| 2 | Usage error |
| 3 | Not signed in |
| 4 | Unreachable, or a server error |
| 5 | The agent's turn failed or was stopped |
| 6 | Timed out waiting |

The npm package ships a skill, `skills/vespin/SKILL.md`, that teaches a coding agent the commands, `--json`, and these codes. For Claude Code, copy the `skills/vespin` folder into `~/.claude/skills/`. For Codex and Cursor, add the skill's text to your `AGENTS.md`. To connect an agent to Vespin without a shell, use [Vespin MCP](https://vespin.dev/docs/vespin-mcp.md) instead.

`vespin --help`, and `--help` on any command, lists every command with examples.