> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC Courier CLI reference

> Every command, option, environment variable and exit code of trusset-kyc.

`trusset-kyc` has a bank side and a verifier side. Every command accepts the common options.

```
trusset-kyc <command> [options]
```

## Common options

| Option | Meaning |
| - | - |
| `--home <dir>` | The keystore directory. Default `./.trusset-kyc`, or the environment variable `TRUSSET_KYC_HOME` |
| `--json` | Print one machine-readable JSON line on stdout instead of text |
| `--api <url>` | The Trusset API address for the bank commands `pull` and `open`. Default `TRUSSET_API_URL`, or `https://api.trusset.org`. Every other command refuses this option. Verifier commands take the address from the invite |
| `--help`, `-h` | Help for the tool or for one command |
| `--version`, `-V` | The version |

## Environment variables

| Variable | Meaning |
| - | - |
| `TRUSSET_API_KEY` | The bank's instance API key, for `pull` and `open`. Read from the environment only. Never written to disk and never printed |
| `TRUSSET_KYC_PASSPHRASE` | When set while a key is created, the private key is stored encrypted. It is then required whenever the key is used |
| `TRUSSET_KYC_HOME` | The keystore directory |
| `TRUSSET_API_URL` | The Trusset API address for the bank commands |

The API address must use `https`. Plain `http` is accepted only for `localhost`, `127.0.0.1` and `[::1]`.

## Bank commands

### keygen

```bash theme={null}
trusset-kyc keygen
```

Creates an X25519 record key pair and stores it in the keystore. Prints the public key, the key ID and the fingerprint. Running it again adds a key and keeps the earlier ones.

### key show

```bash theme={null}
trusset-kyc key show
```

Lists the record keys in the keystore, public parts only, and marks the newest.

### source add, source revoke-key, source list, source remove

```bash theme={null}
trusset-kyc source add --id <sourceId> --name <name> --key <ed25519 public key hex> [--replace --former-key <retire|revoke>]
trusset-kyc source revoke-key --id <sourceId> --key <ed25519 public key hex>
trusset-kyc source list
trusset-kyc source remove --id <sourceId>
```

`source add` pins the signing key of a source. Records from that source are accepted only when signed by this key. A source that is already pinned is refused unless `--replace` is given, and `--replace` needs a decision about the former key. `--former-key retire` is a planned rotation: the former key opens no new record, and records filed while it was pinned still verify. `--former-key revoke` is for a key that was lost or exposed: it opens no new record, and records filed under it no longer verify. `--former-key` without `--replace` is refused. Run `open --all` before you pin a new key, because a former key never opens a record again, whatever date the envelope claims.

`source revoke-key` revokes a retired key that later turned out to be exposed. The current key cannot be revoked this way; pin the new key with `--replace --former-key revoke` instead. A revoked key can never be pinned again, for this or any other source.

`source list` shows how many retired and revoked keys a source has. `source remove` deletes the pin and its retired keys. Its revoked keys stay in the keystore, so removing a source and adding it again does not undo a revocation.

### pull

```bash theme={null}
trusset-kyc pull [--status RECEIVED] [--source <sourceId>] [--wallet <0x...>]
```

Lists the records Trusset holds for your instance. Nothing is decrypted. `--status` takes one of the eight record statuses and defaults to `RECEIVED`. Each line says whether the record's source is pinned and whether the record key it is sealed to is in this keystore.

### open

```bash theme={null}
trusset-kyc open <recordId> --out <dir>
trusset-kyc open --all --out <dir>
```

Downloads, verifies, decrypts and files one record, or every record in status `RECEIVED`, then acknowledges each to Trusset. `--out` is required. Give either one record ID or `--all`. The [bank walkthrough](https://docs.trusset.org/tools/kyc-courier/bank-walkthrough.md#what-open-reports) lists the outcomes.

### verify

```bash theme={null}
trusset-kyc verify <dir> [--key <ed25519 public key hex> | --fingerprint <fingerprint>]
```

Verifies a filed record directory offline. The key in the folder's `source.json` must match a key you trust: the source's pin in this keystore, one of its retired keys for a record sealed before that key was retired, or the key or fingerprint given with `--key` or `--fingerprint`. A revoked key anchors nothing. Without one of these the record does not verify. The envelope signature is always checked, so a receipt without a valid `sealedDigest` or a missing `envelope.sig` makes the record fail. Exits 0 when it verifies and 2 when it does not.

## Verifier commands

### source-keygen

```bash theme={null}
trusset-kyc source-keygen
```

Creates the Ed25519 signing key pair and prints the public key and its fingerprint. A keystore holds one signing key, and the command refuses to overwrite it.

### invite add, invite confirm, invite list, invite remove

```bash theme={null}
trusset-kyc invite add <invite-string> --fingerprint <recipient key fingerprint read out by the bank> [--replace]
trusset-kyc invite confirm --source <sourceId> --fingerprint <recipient key fingerprint read out by the bank>
trusset-kyc invite list
trusset-kyc invite remove --source <sourceId>
```

`invite add` requires `--fingerprint`: the fingerprint of the bank's recipient key as the bank read it out from `trusset-kyc key show` over a channel that does not run through Trusset. The tool checks that the key in the invite has exactly this fingerprint. When it does not, nothing is stored and the command exits with 2 (`FINGERPRINT_MISMATCH`). Without `--fingerprint` nothing is stored and it exits with 1 (`FINGERPRINT_REQUIRED`). When it matches, the invite is stored as confirmed and the tool asks the inbox for the bank's key as a consistency check; when that check fails, the invite stays stored and the command exits with an error that says so. `--replace` is needed to replace a stored invite for the same source.

`invite confirm` confirms an invite stored by version 1.1.0 or earlier, which `seal` and `send` refuse until then (`INVITE_NOT_CONFIRMED`). A wrong fingerprint leaves the invite stored but not confirmed.

`invite list` never shows the token, and shows the recipient key, its key ID and its fingerprint only for a confirmed invite.

### seal

```bash theme={null}
trusset-kyc seal --source <sourceId> --wallet <0x...> --record <file.json> \
  [--attach <file> ...] [--verified-at <ISO or YYYY-MM-DD>] --valid-until <ISO or YYYY-MM-DD> \
  [--out <file>] [--send]
```

Seals and signs a record for the bank named in the stored invite and writes `<envelopeId>.envelope.json`. The invite must be confirmed against the bank's fingerprint. Works offline unless `--send` is given, which checks the bank's key and delivers in the same run. When the delivery fails, the envelope file is kept and can be sent later.

### send

```bash theme={null}
trusset-kyc send <envelope-file>
```

Delivers a sealed envelope. Before it posts, it checks that the envelope is sealed to the key the invite pins, that the timing rules hold, and that the inbox reports the same recipient key. When the keystore holds the signing key, it also checks that the envelope is signed by it.

### status

```bash theme={null}
trusset-kyc status --source <sourceId> <envelopeId>
```

Shows what happened to a delivered record.

### revoke

```bash theme={null}
trusset-kyc revoke --source <sourceId> --wallet <0x...> --digest <recordDigest> \
  --reason <EXPIRED|WITHDRAWN|SUPERSEDED|INVALID|OTHER>
```

Signs and posts a revocation for a delivered record.

## Exit codes

| Code | Meaning |
| - | - |
| 0 | Success |
| 1 | Usage or validation error, including a keystore that other users can read |
| 2 | Verification or cryptographic failure: a signature, digest or key check failed, a source is not pinned, or the bank's key differs from the invite |
| 3 | Network or server error. The message carries the `error.code` and `error.message` Trusset returned |

Errors are written to stderr as one line starting with `error:`, warnings as lines starting with `warning:`.

## JSON output

With `--json` the tool prints one JSON object on one line of stdout. It carries `ok` and `command` plus the result fields of the command. On failure `ok` is `false` and an `error` object holds `code` and `message`. The exit code is the same as without `--json`.

## Network behaviour

Every call has a timeout of 60 seconds, and 300 seconds for uploading and downloading an envelope. Network failures and the status codes `502`, `503` and `504` are retried, up to 3 attempts in total, for calls that are safe to repeat. A `429 RATE_LIMIT_EXCEEDED` answer is waited out and retried, also up to 3 attempts. `INBOX_FULL` is not retried. Redirects are not followed.


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