---
summary: Use the SigID CLI for local agent keys, registration, challenge-response authentication, signing, token caching, and key lifecycle workflows.
tags:
  - cli
  - agents
  - keys
  - registration
  - authentication
categories:
  - AI Agents
---

# CLI Tool

<!-- agent:page
You are a coding agent or operator using sigid-cli for local agent identity workflows by following this reference.
First collect: IDP URL, tenant context if needed, local key label, key algorithm, passphrase source, requested scopes, output format, and whether the task is init, auth, token inspection, x402 payment, signing, verification, key rotation, or revocation.
Use init for first-time local registration, auth for challenge-response token acquisition, token commands for cache inspection or refresh, x402 commands only after a valid cached agent token exists, and key commands for local keystore and server key lifecycle.
Keep keystore and token-cache files private, avoid passphrases in shell history, require HTTPS for non-localhost IDPs, and never print private keys, token cache contents, or passphrases into logs.
Verify the command result, exit status, selected IDP, selected key label, token subject type, and key lifecycle state before reporting success.
-->

The SigID CLI (`sigid-cli`) is the command-line interface for agent identity
workflows. It covers local key management, agent registration,
challenge-response authentication, token caching, signing, verification, and key
lifecycle operations.

This CLI is not a Dashboard administration tool, a general Management API
client, or an OAuth application login helper. For HTTP API integration patterns,
see [API And SDK Reference](../reference/api-sdk-reference.md).

## What this page is for

Use this page when you need to:

- generate and store agent signing keys locally
- initialize a self-registered agent from a terminal
- authenticate an agent with challenge-response
- inspect cached agent tokens
- buy x402-protected resources as an authenticated agent
- sign and verify local payloads
- register, rotate, revoke, or remove agent keys
- script agent identity operations in development or CI

## Install and verify

### From source

Current repository builds install the CLI from the Rust crate:

```bash
cargo install --path crates/sigid-cli
```

Verify the installed binary:

```bash
sigid-cli --version
sigid-cli --help
```

## Before you start

The CLI stores local configuration and sensitive data under `~/.config/sigid/`
unless your environment overrides the platform config directory.

| File | Purpose | Notes |
|---|---|---|
| `~/.config/sigid/config.toml` | CLI defaults | Plain TOML configuration |
| `~/.config/sigid/keys.enc` | Local private-key keystore | Encrypted with Argon2id + AES-256-GCM-SIV |
| `~/.config/sigid/tokens.enc` | Cached access and refresh tokens | Encrypted token cache |
| `~/.config/sigid/tokens.key` | Token-cache master key | Private file permissions |

Passphrase sources are checked in this order:

1. `--passphrase`
2. `--passphrase-stdin`
3. `--passphrase-file`
4. `SIGID_PASSPHRASE`
5. interactive prompt

`--passphrase` exists for automation and tests, but it can be captured in shell
history. Prefer an interactive prompt, `--passphrase-stdin`,
`--passphrase-file`, or `SIGID_PASSPHRASE` in controlled CI environments.

## Initialize an agent

`init` generates a key pair, registers the agent, and caches credentials in one
flow.

```bash
sigid-cli init \
  --idp https://auth.example.com \
  --name my-agent \
  --anchor-type did_key \
  --algo ed25519
```

| Option | Description | Default |
|---|---|---|
| `--idp` | Identity Provider URL | Required |
| `--name` | Agent name and local key label | Required |
| `--anchor-type` | Agent anchor type | `did_key` |
| `--algo` | Key algorithm | `ed25519` |

The CLI:

- generates a local key pair
- registers the agent with `/auth/agent/register`
- falls back to PoW registration through `/auth/agent/register/pow` and
  `/auth/agent/register/pow/complete` when required
- stores the private key in `keys.enc`
- caches returned tokens when the tenant admits the agent

## Authenticate an agent

`auth` performs challenge-response authentication with a local key.

```bash
sigid-cli auth \
  --idp https://auth.example.com \
  --key my-agent \
  --scope "openid wallet:sign"
```

| Option | Description | Default |
|---|---|---|
| `--idp` | Identity Provider URL | `default_idp` from config, otherwise error |
| `--key` | Local key label to use | `default_key` from config, otherwise `default` |
| `--scope` | Requested scopes | None |

The CLI:

- loads the local key from the encrypted keystore
- requests `/auth/agent/challenge`
- signs the canonical challenge
- submits `/auth/agent/verify`
- stores the returned tokens in `tokens.enc`

## Inspect identity and tokens

Show the current local identity and cached agent context:

```bash
sigid-cli whoami
```

Show a cached token for an IDP:

```bash
sigid-cli token --idp https://auth.example.com
```

Refresh a cached token:

```bash
sigid-cli token --refresh --idp https://auth.example.com
```

Clear cached tokens:

```bash
# Clear tokens for one IDP
sigid-cli token --clear --idp https://auth.example.com

# Clear all cached tokens
sigid-cli token --clear
```

## Buy x402-protected resources

`x402 buy` quotes and immediately executes an outbound x402 purchase using the
cached agent token for the IDP.

```bash
sigid-cli x402 buy \
  --idp https://auth.example.com \
  --url https://merchant.example.com/resource \
  --header "Accept: application/json"
```

The CLI calls the agent-authenticated `/agent/x402/pay/quote` route first, then
executes the returned quote through `/agent/x402/pay/execute`. Run
`sigid-cli auth` first if no valid cached token is available.

For merchants using SigID Commerce payment links, use `x402 commerce-link`.
The CLI builds the commerce x402 endpoint and pays it through the same agent
outbound x402 flow:

```bash
sigid-cli x402 commerce-link \
  --idp https://auth.example.com \
  --merchant https://merchant.example.com \
  --payment-link-token plink_abc123 \
  --buyer-country US \
  --buyer-type business
```

| Option | Description | Default |
|---|---|---|
| `--idp` | Identity Provider URL | `default_idp` from config, otherwise error |
| `--url` | x402-protected resource URL | Required |
| `--method` | Outbound method: `GET` or `HEAD` | `GET` |
| `--header` | Outbound header; only `Accept` and `Accept-Language` are supported | None |
| `--payment-route` | `facilitator` or `wallet` | `facilitator` |
| `--payer-mode` | `sigid_funded`, `user_authorized`, or `tenant_funded` | `sigid_funded` |
| `--idempotency-key` | Caller idempotency key bound to the quote | None |
| `--payment-required-file` | JSON file containing a captured x402 402 response body | None |
| `--payment-payload-file` | JSON file containing a signed x402 payment payload for `user_authorized` mode | None |

`x402 commerce-link` additionally accepts:

| Option | Description | Default |
|---|---|---|
| `--merchant` | Merchant SigID Commerce origin | Required |
| `--payment-link-token` | SigID Commerce payment-link token | Required |
| `--buyer-country` | Buyer country for merchant policy checks | None |
| `--buyer-region` | Buyer region for merchant policy checks | None |
| `--buyer-type` | `unknown`, `consumer`, or `business` | None |

For manual quote and execution flows:

```bash
sigid-cli x402 quote \
  --idp https://auth.example.com \
  --url https://merchant.example.com/resource

sigid-cli x402 execute \
  --idp https://auth.example.com \
  --quote-id 018f3d44-7d4d-7d5d-8d3b-9f0c4c37a111

sigid-cli x402 status \
  --idp https://auth.example.com \
  --payment-id 018f3d44-7d4d-7d5d-8d3b-9f0c4c37a111
```

Outbound x402 quotes are short lived. Execute a quote immediately, or use
`x402 buy` for the normal one-step purchase path.

## Manage local keys

Generate a local key pair:

```bash
sigid-cli keygen --algo ed25519 --label my-agent
```

| Option | Description | Default |
|---|---|---|
| `--algo` | Key algorithm: `ed25519`, `es256`, `es256k`, or `bip340` | `ed25519` |
| `--label` | Local key label | `default_key` from config, otherwise `default` |

`keygen` prints the public key and fingerprint. It does not print the private
key. The private key is encrypted and stored in the local keystore.

List local keys:

```bash
sigid-cli list-keys
```

Remove a key from the local keystore:

```bash
sigid-cli remove-key --key old-key
```

`remove-key` only deletes the local keystore entry. To revoke a registered key
on the IDP, use `revoke-key`.

## Register, rotate, and revoke keys

Register an additional local key with the IDP:

```bash
sigid-cli register-key \
  --idp https://auth.example.com \
  --key backup-key
```

`register-key` requires a valid cached token. Run `sigid-cli auth` first if no
valid token is available.

Rotate a key:

```bash
sigid-cli rotate-key \
  --idp https://auth.example.com \
  --old my-agent \
  --new-label my-agent-v2
```

| Option | Description | Default |
|---|---|---|
| `--old` | Label of the old local key | Required |
| `--new-label` | Label for the new key | `{old}_v2` |
| `--new-algo` | Algorithm for the new key | Same as old key |

The CLI generates a new key pair, registers the new key, saves it locally, and
deprecates the old key on the IDP.

Revoke a key:

```bash
sigid-cli revoke-key \
  --idp https://auth.example.com \
  --key compromised-key \
  --reason "key exposed"
```

`revoke-key` marks the registered key as revoked on the IDP. It preserves the
local key so you can inspect or archive it. Use `remove-key` to delete the local
keystore entry.

## Sign and verify payloads

Sign a message:

```bash
sigid-cli sign --message "Hello, SigID!" --key my-agent
```

Sign a file:

```bash
sigid-cli sign --file transaction.json --key my-agent
```

The signature output includes a base64-encoded signature, algorithm,
fingerprint, and timestamp.

Verify a message signature:

```bash
sigid-cli verify \
  --message "Hello, SigID!" \
  --signature "base64-signature" \
  --public-key "hex-encoded-public-key" \
  --algo ed25519
```

Verify a file signature:

```bash
sigid-cli verify \
  --file transaction.json \
  --signature-file transaction.sig \
  --public-key "hex-encoded-public-key" \
  --algo ed25519
```

`--signature` expects a base64-encoded signature. `--signature-file` reads a raw
binary signature file.

Create a GPG-compatible detached signature:

```bash
sigid-cli gpg-sign --file artifact.tar.gz --key my-agent
sigid-cli gpg-sign --file artifact.tar.gz --key my-agent --armor
```

Without `--armor`, the CLI writes a binary `.sig` file. With `--armor`, it
writes a `.sig.asc` file.

## Configuration and storage

Create `~/.config/sigid/config.toml` to set defaults:

```toml
default_idp = "https://auth.example.com"
default_key = "my-agent"
output_format = "json"
```

| Field | Description |
|---|---|
| `default_idp` | Default Identity Provider URL |
| `default_key` | Default local key label |
| `output_format` | Default output format: `json`, `yaml`, `text`, `table`, or `quiet` |

Supported environment variables:

| Variable | Purpose |
|---|---|
| `SIGID_PASSPHRASE` | Keystore passphrase for automation |
| `SIGID_LOG_LEVEL` | CLI logging level |
| `RUST_LOG` | Fallback logging configuration |

Supported global flags:

```bash
--output json|yaml|text|quiet|table
--keystore /path/to/keys.enc
```

Non-localhost IDP URLs must use HTTPS. Local development URLs such as
`http://localhost:3000` are allowed.

## Output formats and scripting

JSON is the default output format:

```bash
sigid-cli whoami --output json
```

Other formats are available for humans and scripts:

```bash
sigid-cli list-keys --output table
sigid-cli token --output quiet
sigid-cli whoami --output yaml
```

The CLI exits with `0` on success and a non-zero code on errors.

## Keystore security

The local keystore is designed for agent development and operator workflows:

- private keys are encrypted at rest in `keys.enc`
- the keystore uses Argon2id-derived keys and AES-256-GCM-SIV encryption
- keystore and token files are written atomically with restrictive permissions
- the token cache is encrypted separately from the private-key keystore
- non-localhost IDP URLs must use HTTPS to avoid exposing bearer tokens

Keep the keystore passphrase outside source control and avoid passing it through
shell history.

## Common errors

| Error | Meaning | Fix |
|---|---|---|
| `no IDP URL specified` | No `--idp` flag and no `default_idp` in config | Pass `--idp` or set `default_idp` |
| `no valid token - authenticate first with sigid-cli auth` | The IDP operation needs a cached token | Run `sigid-cli auth` |
| `no refresh token available` | The cached token cannot be refreshed | Re-authenticate with `sigid-cli auth` |
| `key '<name>' has no server_key_id` | The local key has not been registered with the IDP | Run `sigid-cli register-key` first |
| `default_idp must use https for non-localhost hosts` | Remote IDP URL uses plain HTTP | Use HTTPS for non-localhost IDPs |
| `provide --message or --file` | Signing or verification input is missing | Pass one input source |
| `provide --signature or --signature-file` | Verification signature is missing | Pass one signature source |
| Signature verification failure | Payload, public key, algorithm, or signature does not match | Re-check the exact bytes and algorithm |

## Command reference

| Command | Purpose |
|---|---|
| `init` | Generate a key, register an agent, and cache tokens |
| `keygen` | Generate a local key pair |
| `sign` | Sign a message or file |
| `verify` | Verify a signature |
| `gpg-sign` | Create a GPG-compatible detached signature |
| `auth` | Perform agent challenge-response authentication |
| `token` | Show, refresh, or clear cached tokens |
| `register-key` | Register a local key with the IDP |
| `list-keys` | List local keystore entries |
| `whoami` | Show local identity and cached agent context |
| `rotate-key` | Generate and register a replacement key, then deprecate the old key |
| `revoke-key` | Revoke a registered key on the IDP |
| `remove-key` | Remove a key from the local keystore |
| `schema export` | Export database schema for development or operator workflows |

## See also

- [Agent Authentication](agent-auth.md)
- [Agent Registration](registration.md)
- [API And SDK Reference](../reference/api-sdk-reference.md)