sumvin errand

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.

An errand is a long-running purchase task that runs under a Stamped Mandate. sumvin errand covers the whole lifecycle: creating one, checking on it, answering its questions, and deciding whether to approve what it wants to buy.

sumvin errand create "<what you want done>"
sumvin errand list
sumvin errand get <id>
sumvin errand events <id>
sumvin errand clarify <id> --answer 1=<text>
sumvin errand approve <id>
sumvin errand reject <id>
sumvin errand cancel <id>

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

Coming soon: payments arrive in a fast-follow release.

errand create is available to accounts in the early-access group. The other verbs — list, get, events, clarify, cancel — work for any account that already has errands.

`sumvin errand create`

Submits a plain-language request.

sumvin errand create "Order two boxes of A4 paper"

Flags

Flag	Effect
`<intent>` (required)	Plain-language description of what you want done.
`--intent-type`	`product`, `service`, or `composite`. Defaults to `product`.
`--idempotency-key <value>`	Lets you retry safely after a dropped connection without creating a duplicate — the CLI prints one automatically for you to reuse.

Output states

Created: the errand’s ID and its starting status.
Retried with the same idempotency key: the same errand, reported as already existing rather than duplicated.
Not in the early-access group: the command refuses and tells you so.

`sumvin errand list` and `sumvin errand get`

sumvin errand list --status pending_approval
sumvin errand get <id> --expand mandate

list filters by status, intent type, and sort order. get shows one errand in full, and can expand its mandate or spend details inline. Errand statuses: qualifying, searching, validating, pending_approval, pending_clarification, approved, monitoring, executing, completed, failed, expired, cancelled.

`sumvin errand events`

Lists the activity log for one errand — every status change and clarification, in order.

sumvin errand events <id>

`sumvin errand clarify`

Answers a question the agent asked before it can continue.

sumvin errand clarify <id> --answer 1="My budget is 200"

Each --answer N=<text> answers question N from sumvin errand get. Repeat the flag to answer more than one question in the same call.

`sumvin errand approve` and `sumvin errand reject`

Once an errand has assembled a purchase, it waits for your decision. Approving needs a local signing key — see sumvin keys — because your approval has to be provably yours, not something Sumvin’s own systems could produce on your behalf.

sumvin errand approve <id>

The CLI shows you the mandate before asking for confirmation:

Errand:  ipa_01HQ8ZK3M4N5P6R7S8T9V0W1X2

Authorise a purchase for this errand. Purchase proceeds only while all of the
following hold:
- the price is at most 180 USD
- availability is one of: in_stock

Ceiling: Up to USD 200.00
Expires: 2026-08-12T07:30:00.000Z

Approve this errand's purchase?

Read the ceiling as carefully as the statement — the statement’s wording doesn’t carry the spend limit, so two errands with identical wording can carry different caps.

sumvin errand reject <id>

Rejecting is terminal: the errand is cancelled and its reservation released. It needs no key, because it authorizes nothing. Flags (both commands)

Flag	Effect
`--yes`	Skip the confirmation prompt. Required in any non-interactive session. Never give it to an unattended agent: it approves without you.

Output states

Approved: the errand moves on to monitoring and execution, within the ceiling you signed.
Rejected: the errand is cancelled.
“Not awaiting approval”: only an errand in pending_approval can take a decision.
“Mandate has expired”: approving is refused once the deadline passes — reject it instead to release the reservation and start again.

`sumvin errand cancel`

Stops an errand that’s still in progress.

sumvin errand cancel <id>

Exit codes

Every verb uses 0 for success and 1 for failure. Cancelling an errand that’s already in a terminal status still exits 0 — the end state you wanted already holds.

Try asking your agent: “Check whether my last errand needs anything from me.”

MCP server

CLI

Status and errors

`sumvin errand create`

`sumvin errand list` and `sumvin errand get`

`sumvin errand events`

`sumvin errand clarify`

`sumvin errand approve` and `sumvin errand reject`

`sumvin errand cancel`

Exit codes

​sumvin errand create

​sumvin errand list and sumvin errand get

​sumvin errand events

​sumvin errand clarify

​sumvin errand approve and sumvin errand reject

​sumvin errand cancel

​Exit codes

`sumvin errand create`

`sumvin errand list` and `sumvin errand get`

`sumvin errand events`

`sumvin errand clarify`

`sumvin errand approve` and `sumvin errand reject`

`sumvin errand cancel`

Exit codes