CLI Tool¶

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.

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:

cargo install --path crates/sigid-cli

Verify the installed binary:

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:

--passphrase
--passphrase-stdin
--passphrase-file
SIGID_PASSPHRASE
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.

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.

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:

sigid-cli whoami

Show a cached token for an IDP:

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

Refresh a cached token:

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

Clear cached tokens:

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

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:

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:

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:

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:

sigid-cli list-keys

Remove a key from the local keystore:

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:

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:

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:

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:

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

Sign a file:

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:

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

Verify a file signature:

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:

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:

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:

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

sigid-cli whoami --output json

Other formats are available for humans and scripts:

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