> ## 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: "",
  payments: "",
  openBanking: "",
  developers: "",
  verifiers: ""
};

<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. `sumvin errand` covers the whole lifecycle: creating one, checking on it, answering its questions, and deciding whether to approve what it wants to buy.

```bash theme={null}
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>
```

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

```bash theme={null}
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`

```bash theme={null}
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.

```bash theme={null}
sumvin errand events <id>
```

## `sumvin errand clarify`

Answers a question the agent asked before it can continue.

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

```bash theme={null}
sumvin errand approve <id>
```

The CLI shows you the mandate before asking for confirmation:

```text theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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>