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

> Manage the local signing key you use to approve mandates and errands yourself.

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

This group is entirely optional. Without it, Sumvin's agent signs on your behalf whenever a Stamped Mandate is created. You reach for `sumvin keys` when you'd rather approve things yourself, from a key you hold, on a machine you chose.

```bash theme={null}
sumvin keys generate       # create the key
sumvin keys add-to-safe    # register your key with your account
sumvin keys show           # see the key's address and registration status
```

<Warning>
  Registering a key with your account can't be undone yet. There's currently no command to remove a registered key — plan for that before you register one.
</Warning>

## `sumvin keys generate`

Creates a signing key and stores it on this machine.

**Flags**

| Flag      | Effect                                               |
| --------- | ---------------------------------------------------- |
| `--force` | Replace an existing key. Not reversible — see below. |
| `--json`  | Print a result object instead of the formatted view. |

**Output states**

* Success prints the key's address. The key itself is never printed, by this command or any other — only the address, which is safe to share.
* If a key already exists, the command refuses and tells you to use `--force` or run `sumvin keys show` to see the one you have. If your existing key has already been registered with your account, overwriting it without a way to unregister the old one leaves that old key with standing authority and no copy of it on this machine — `--force` proceeds anyway, deliberately.

## `sumvin keys add-to-safe`

Registers your local key's address with your account and waits for the registration to settle.

**Flags**

| Flag                 | Effect                                                                  |
| -------------------- | ----------------------------------------------------------------------- |
| `--timeout <window>` | How long to wait for the registration to settle. Defaults to 5 minutes. |
| `--json`             | Silence the progress narration and print one result once it settles.    |

Only the key's public address ever leaves this machine.

**Output states**

* `pending` while the registration is in progress, then a confirmation once it's active.
* Registration can fail. A failed registration is a failed run, not a state to retry blindly — check `sumvin keys show` before trying again.

```bash theme={null}
sumvin keys add-to-safe --json
```

```json theme={null}
{
  "ok": true,
  "exit_code": 0,
  "command": "keys add-to-safe",
  "data": {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "signer_status": "active"
  }
}
```

## `sumvin keys show`

Shows your local key's address and whether it's registered with your account.

**Flags**

| Flag     | Effect                                               |
| -------- | ---------------------------------------------------- |
| `--json` | Print a result object instead of the formatted view. |

**Output states**

* If you've generated a key, its address and registration status (registered, not registered, or unchecked if you're signed out).
* If no key exists yet, the command says so and points at `sumvin keys generate`.

## Exit codes

All three commands use `0` for success and `1` for failure — a registration that fails to settle is a failed run, not a negative answer.