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. You ask. You sign. Then Sumvin searches, checks the merchant, watches for your conditions, and settles the purchase. sumvin errand covers the whole lifecycle: creating one, signing or declining its bounds, checking on it, and answering its questions.

sumvin errand create "<what you want done>" --max <amount> --currency <code>
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, with the most it may spend and the currency.

sumvin errand create "Order two boxes of A4 paper" --max 200 --currency USD

Creating an errand authorises nothing. The errand then waits at pending_approval for your signature before it searches for anything — see sumvin errand approve below. Flags

Flag	Effect
`<intent>` (required)	Plain-language description of what you want done.
`--max <amount>` (required)	The most the errand may spend, as a positive amount in major units — for example `200` or `180.50`.
`--currency <code>` (required)	The currency of `--max`, as a three-letter code — for example `GBP` or `USD`.
`--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.
Missing or malformed limit: if --max or --currency is missing or isn’t in the right shape, the CLI refuses before contacting Sumvin: An errand needs the most it may spend and the currency it is in. Set it with --max <amount> and --currency <code>, e.g. --max 200 --currency GBP.
Limit refused by Sumvin: an unsupported currency, or an amount finer than the currency holds, is refused — the CLI shows the reason with the same hint.

`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, in lifecycle order: qualifying, pending_clarification, pending_approval, approved, searching, validating, monitoring, executing, completed, failed, expired, cancelled. At pending_approval, nothing has been searched yet.

`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. Questions come before you sign.

sumvin errand clarify <id> --answer 1="White, 80gsm"

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`

After you create an errand, and answer any question it has, it waits for your signature before it searches for anything. approve signs the errand’s bounds: what you asked for, the most it may spend and the currency, any conditions, and when the authorisation lapses. 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

You are signing this errand's bounds, not a chosen product. Nothing has been
searched for yet; a match found within these bounds is bought without asking again.

Authorise a purchase: “Order two boxes of A4 paper”, spending up to 200.00 USD. The purchase is paid with your Visa card ending 4242. It proceeds only while all of the following hold:
- the price is at most 180 USD
- availability is one of: in_stock
A match found within these bounds is bought without asking again. This authorisation lapses on 12 Aug 2026, 07:30 UTC.

Ceiling: Up to USD 200.00
Expires: 2026-08-12T07:30:00.000Z (6:59:12)

Sign this errand's bounds? A match within them will be bought without asking you again.

You’re signing bounds, not a chosen product. Once you sign, a match found within them is bought without asking you again — there’s no second look at the pick. Read the ceiling and the conditions as carefully as the statement — they are what decides whether a match is bought.

sumvin errand reject <id>

Rejecting is terminal: the errand is cancelled and its reservation released. Nothing is signed, searched, or spent. It needs no key, because it authorises 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 search, checks the merchant, watches for your conditions, and settles the purchase — all within the bounds 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 and start a new errand.

`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