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

> Verify your identity from the terminal.

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

Verification is what unlocks the parts of Sumvin that need a verified person behind them. The CLI drives everything except two steps a human has to do: typing a code that arrives by SMS, and photographing a document in a browser.

```bash theme={null}
sumvin kyc start                # verify your phone, then open the browser step
sumvin kyc status               # where verification has got to right now
sumvin kyc status --wait        # block until there's a result
```

Both commands need a signed-in session — see [`sumvin login`](/reference/cli/auth).

<Warning>
  `sumvin kyc start` can't be scripted. It needs a browser and a code sent by SMS. Build automation around `sumvin kyc status --json` instead.
</Warning>

## `sumvin kyc start`

Checks where you already are, verifies your phone number if that hasn't happened yet, then opens a single-use browser link for the document step.

**Flags**

| Flag               | Effect                                                                                                         |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `--phone <number>` | Your phone number, in international format. You're still prompted for the SMS code — there's no flag for that. |
| `--json`           | Print a result object instead of the running commentary.                                                       |

**Example**

```bash theme={null}
sumvin kyc start --phone +14155551234
```

**Output states**

* A fresh run prompts for your phone (if needed) and the SMS code, then prints a browser link that expires in about 15 minutes.
* Re-running after an interruption picks up where you left off — it skips a phone step you already completed and reuses your existing verification record.
* Already verified: the command tells you so and mints nothing.
* Previously declined: the command refuses. A declined verification can't be retried with the same documents.

## `sumvin kyc status`

Reports where verification has got to. Always exits successfully — it reports state, it doesn't judge it.

**Flags**

| Flag                 | Effect                                                                           |
| -------------------- | -------------------------------------------------------------------------------- |
| `--wait`             | Poll until there's a result instead of a snapshot.                               |
| `--timeout <window>` | How long `--wait` keeps polling. Defaults to 15 minutes.                         |
| `--refresh`          | Ask the verification provider for a live answer. Ignored together with `--wait`. |
| `--json`             | Print the result object instead of the formatted view.                           |

**Example**

```bash theme={null}
sumvin kyc status --wait --timeout 30m
```

**The five statuses**

| Status        | Meaning                                                            |
| ------------- | ------------------------------------------------------------------ |
| `pending`     | You haven't started.                                               |
| `in_progress` | A verification is under way and hasn't returned a result.          |
| `retry`       | More information was requested — resubmit with `sumvin kyc start`. |
| `approved`    | Verified.                                                          |
| `rejected`    | Declined. Terminal — the same documents can't be resubmitted.      |

Once approved, `sumvin kyc status` also reports whether your Sigil exists yet. "Not started" is a normal, expected answer here — see [Sigil](/reference/cli/sigil).

**Exit codes**

| Invocation                 | Result                                  | Exit |
| -------------------------- | --------------------------------------- | ---- |
| `sumvin kyc status`        | any status                              | `0`  |
| `sumvin kyc status --wait` | approved                                | `0`  |
| `sumvin kyc status --wait` | rejected, or more information requested | `2`  |
| `sumvin kyc status --wait` | timed out with no answer yet            | `1`  |

```bash theme={null}
sumvin kyc status --wait --json
```

```json theme={null}
{
  "ok": true,
  "exit_code": 0,
  "command": "kyc status",
  "data": {
    "status": "approved",
    "verified_at": 1754818264000,
    "rejected_at": null,
    "reject_reason": null,
    "sigil": { "did_mint_status": null, "did_token_id": null }
  },
  "next": [ { "command": "sumvin sigil show", "reason": "See the full picture." } ]
}
```