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

# Use the CLI with your agent

> Let a terminal agent drive the Sumvin CLI on your behalf.

export const waitlists = {
  earlyAccess: "",
  payments: "",
  openBanking: "",
  developers: "",
  verifiers: ""
};

<Note>
  **Private preview:** this is rolling out and may not be available on your account yet.{waitlists.earlyAccess ? <> <a href={waitlists.earlyAccess}>Request early access →</a></> : null}
</Note>

<Warning>
  **The CLI is for developers.** It's mainly for people building and experimenting on Sumvin. The recommended way to use Sumvin is the [MCP connector](/get-started/connect), or the API if you're building (docs coming).

  An agent running in your terminal can approve Stamped Mandates that the CLI signs for you. Never give an unattended agent `--yes`.
</Warning>

A packaged skill for terminal agents (Claude Code, Cursor, and similar tools) is on the way. Until it ships, any agent that can run shell commands can already drive `sumvin` today — tell it how, using the instructions below.

## The `--json` contract

Every `sumvin` command accepts a `--json` flag. Instead of the human-readable text, it prints exactly one JSON document to standard output and nothing else — no progress messages, no partial lines, nothing on standard error to interleave with it.

The shape is consistent across every command:

```json theme={null}
{
  "ok": true,
  "exit_code": 0,
  "command": "whoami",
  "data": { },
  "next": [ ]
}
```

A few things worth telling your agent explicitly:

* `ok` means the command ran to completion. It is **not** the answer to a yes/no question — a mandate that fails verification is still a successful, `ok: true` run. Read `exit_code` (`0` succeeded, `1` the run failed, `2` the run succeeded and the answer is no) for the actual verdict.
* `data` carries the result on success; `error` carries a structured code, title, and detail on failure.
* `next` suggests the command to run after this one, so an agent can chain steps without guessing.
* Running `sumvin --json` with no command returns the entire command surface as a single catalog — an agent can learn every command, flag, and exit code from one call, without reading `--help` text written for humans.

## Tell your agent to use it

Paste this into a terminal-agent session that has `sumvin` on its `PATH`:

<Frame>
  ```text theme={null}
  Use the sumvin CLI to help me manage my Sumvin account. Always pass --json
  and read the "exit_code" field for the real result — "ok": true only means
  the command ran, not that the answer was yes. Run `sumvin --json` first to
  see the full list of commands, their flags, and what each exit code means.
  Never run a command that signs, approves, or spends without asking me first
  and showing me exactly what it will do.
  ```
</Frame>

<Warning>
  An agent with shell access to `sumvin` can read anything your signed-in account can read. It can also approve: the CLI signs with the key on your machine, so an agent in your terminal can approve a Stamped Mandate or an errand, and `--yes` skips the prompt that would have stopped to ask you. Approve things yourself, and never give an unattended agent `--yes`.
</Warning>

## What's coming

A packaged skill will let you add the CLI to a terminal agent with one command, instead of pasting instructions by hand. It isn't published yet.

<Tip>**Try asking your agent:** "Show me every sumvin command and what it does."</Tip>