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

# sumvin errand

> Create and manage agentic purchase errands from the terminal.

export const waitlists = {
  earlyAccess: "https://sumvin.com/?interest=early_access&utm_source=docs&utm_medium=banner&utm_campaign=early_access#waitlist",
  payments: "https://sumvin.com/?interest=payments&utm_source=docs&utm_medium=banner&utm_campaign=payments#waitlist",
  openBanking: "https://sumvin.com/?interest=open_banking&utm_source=docs&utm_medium=banner&utm_campaign=open_banking#waitlist",
  developers: "https://sumvin.com/developers?interest=cli,agent_plugin&utm_source=docs&utm_medium=banner&utm_campaign=developers#access",
  verifiers: "https://sumvin.com/developers?interest=verifiers&utm_source=docs&utm_medium=banner&utm_campaign=verifiers#access"
};

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

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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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>
```

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

<Note>
  **Coming soon:** payments arrive in a fast-follow release.{waitlists.payments ? <> <a href={waitlists.payments}>Join the waitlist →</a></> : " A waitlist opens shortly."}
</Note>

<Info>
  `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.
</Info>

## `sumvin errand create`

Submits a plain-language request, with the most it may spend and the currency.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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`

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sumvin errand events <id>
```

## `sumvin errand clarify`

Answers a question the agent asked before it can continue. Questions come before you sign.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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`](/reference/cli/keys) — because your approval has to be provably yours, not something Sumvin's own systems could produce on your behalf.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sumvin errand approve <id>
```

The CLI shows you the mandate before asking for confirmation:

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

<Tip>**Try asking your agent:** "Check whether my last errand needs anything from me."</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.