Use the CLI with your agent

Private preview: this is rolling out and may not be available on your account yet.

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, 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.

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:

{
  "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:

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.

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.

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.

Try asking your agent: “Show me every sumvin command and what it does.”

Start here

Connect your agent

Use the CLI

Your first

Use the CLI with your agent

The `--json` contract

Tell your agent to use it

What’s coming

​The --json contract

​Tell your agent to use it

​What’s coming

The `--json` contract

Tell your agent to use it

What’s coming