CLI Reference

The Credat CLI lets you create agent identities, issue delegation credentials, verify trust chains, inspect tokens, manage revocation, and run handshake flows from the terminal — no code required.

Installation


npm install -g @credat/cli

Requires Node.js 22+.

Quick start


# 1. Create an agent identity
credat init --domain acme.corp
 
# 2. Delegate scopes to the agent
credat delegate --scopes payments:read,invoices:create --until 2026-12-31
 
# 3. Verify the delegation
credat verify
 
# 4. Inspect the raw token
credat inspect
 
# 5. Audit against security best practices
credat audit
 
# 6. Check current state
credat status

Commands

`credat init`

Create an agent identity with did:web. Generates a key pair, DID, and DID Document, then saves them to .credat/ in the current directory.


credat init --domain acme.corp
credat init --domain acme.corp --path agents/assistant
credat init --domain acme.corp --algorithm EdDSA
credat init --domain acme.corp --force  # overwrite existing
credat init --domain acme.corp --output keys/agent.json

Option	Description
`-d, --domain <domain>`	Domain for `did:web` (required)
`-p, --path <path>`	Optional sub-path for the DID
`-a, --algorithm <alg>`	`ES256` (default) or `EdDSA`
`-f, --force`	Overwrite existing agent identity
`-o, --output <file>`	Custom output path (default: `.credat/agent.json`)

Output: Creates .credat/agent.json (or custom path) with the agent identity and .credat/owner.json with the owner key pair.

`credat delegate`

Issue a delegation credential from the owner to the agent.


credat delegate --scopes payments:read,invoices:create
credat delegate --scopes payments:read --max-value 1000 --until 2026-12-31
credat delegate --agent did:web:other.agent --scopes admin:read
credat delegate --scopes files:read --output tokens/delegation.json

Option	Description
`-a, --agent <did>`	Agent DID (defaults to `.credat/agent.json`)
`-s, --scopes <scopes>`	Comma-separated scopes (required)
`-m, --max-value <n>`	`maxTransactionValue` constraint
`-u, --until <date>`	Expiration date (ISO 8601)
`-o, --output <file>`	Custom output path (default: `.credat/delegation.json`)

Output: Saves the signed delegation token to .credat/delegation.json (or custom path).

`credat verify [token]`

Verify a delegation token’s signature, expiration, and scopes. If no token is provided, reads from .credat/delegation.json.


credat verify
credat verify eyJhbGciOiJFUzI1NiIs...
credat verify --json

Prints the verified agent DID, owner DID, scopes, constraints, and validity window.

`credat inspect [token]`

Decode and inspect a delegation token without verifying its signature. Useful for debugging token contents, checking expiration, and viewing selective disclosures.


credat inspect
credat inspect eyJhbGciOiJFUzI1NiIs...
credat inspect --file tokens/delegation.json
credat inspect --json

Option	Description
`-f, --file <path>`	Read token from a file (JSON with `token` field, or raw token)

Token resolution order: --file flag → direct argument → .credat/delegation.json

Output:

Header: JWT algorithm, type, key ID
Payload: Issuer, subject, credential type, agent, owner, timestamps
Selective Disclosures: Name-value pairs
Expiration status: valid, expired, not yet valid, or no expiry set

`credat revoke`

Revoke a delegation credential by flipping a bit in a status list.


credat revoke
credat revoke --token eyJhbGci... --index 42
credat revoke --status-list custom/status.json

Option	Description
`-t, --token <token>`	Delegation token (defaults to `.credat/delegation.json`)
`-s, --status-list <path>`	Status list file path (default: `.credat/status-list.json`)
`-i, --index <number>`	Status list index to revoke (extracted from token if not provided)

If no status list file exists, one is created automatically. The operation is idempotent — revoking an already-revoked index succeeds silently.

`credat audit [token]`

Validate a delegation token against security best practices. Checks expiration, scope breadth, constraints, revocation endpoint, not-before, and issuer/subject claims.


credat audit
credat audit eyJhbGciOiJFUzI1NiIs...
credat audit --json

Audit rules:

Rule	Pass	Warn	Fail
Expiration	Valid range	Expires in > 365 days	Token expired
Scopes	Appropriate count/specificity	Broad scopes (`:*`, `admin`), or > 10 scopes	—
Constraints	`maxTransactionValue` set	No constraints set	—
Revocation	Status list configured	—	No revocation endpoint
Not-before	Present and active	Token not yet valid	—
Issuer/Subject	Both present	—	Missing `iss` or `sub` claim

Output example:


  ✓ Expires in 90 days
  ⚠ Broad scopes detected: payments:* — consider narrowing
  ✗ No revocation endpoint configured

  3 passed · 1 warning · 1 issue

`credat renew`

Renew a delegation with a new expiry date. Re-issues the existing delegation with the same agent, owner, scopes, and constraints but a new validUntil.


credat renew --until 2027-06-30T23:59:59Z
credat renew --until 2027-06-30 --json

Option	Description
`-u, --until <date>`	New expiration date, ISO 8601 (required, must be in the future)

Reads the existing delegation from .credat/delegation.json and owner from .credat/owner.json. Saves the renewed delegation back to .credat/delegation.json.

`credat status`

Show the current .credat/ state: agent identity, owner key, and delegation info.


credat status
credat status --json

`credat demo`

Run a full interactive trust flow demo. Creates identities, delegates scopes, verifies the delegation, and completes a challenge-response handshake — all in one command.


credat demo

This is the fastest way to see Credat in action without writing any code.

Handshake commands

The credat handshake subcommands let you perform individual steps of the trust handshake from the terminal.

`credat handshake challenge`

Create a challenge for an agent to respond to.


credat handshake challenge --from did:web:service.example.com
credat handshake challenge --from did:web:service.example.com --json

Option	Description
`--from <did>`	Challenger DID (required)

Output: A ChallengeMessage JSON with type, nonce, from, and timestamp.

`credat handshake present`

Present credentials in response to a challenge.


credat handshake present --challenge '{"type":"credat:challenge","nonce":"...","from":"did:web:service.example.com","timestamp":"..."}'

Option	Description
`--challenge <json>`	Challenge JSON string (required)

Loads agent from .credat/agent.json and delegation from .credat/delegation.json.

Output: A PresentationMessage JSON to send back to the challenger.

`credat handshake verify`

Verify a presentation against a challenge.


credat handshake verify --presentation '{"type":"credat:presentation",...}' --challenge '{"type":"credat:challenge",...}'

Option	Description
`--presentation <json>`	Presentation JSON string (required)
`--challenge <json>`	Challenge JSON string (required)

Loads owner and agent keys from .credat/. Prints verification result with agent DID, scopes, and any errors.

`credat handshake demo`

Run a full handshake demo between two in-memory agents. No files or arguments needed.


credat handshake demo
credat handshake demo --json

Creates a service, an agent, delegates scopes, performs the challenge-response flow, and shows the result.

Key management

The credat keys subcommands let you export, import, and inspect key pairs.

`credat keys export`

Export a key pair in JWK format.


credat keys export             # exports agent keys (default)
credat keys export --as owner  # exports owner keys
credat keys export --json

Option	Description
`--as <type>`	`agent` (default) or `owner`

Warning: Output includes private key material. Store it securely and never share it.

`credat keys import <jwk-data>`

Import a key pair from JWK JSON.


credat keys import '{"algorithm":"ES256","publicKey":{...},"privateKey":{...}}'
credat keys import '...' --as owner

Option	Description
`--as <type>`	Import as `agent` (default) or `owner`

The JWK JSON must include algorithm, publicKey, and privateKey (with the d field).

`credat keys list`

List current key fingerprints without exposing key material.


credat keys list
credat keys list --json

Shows type, DID, algorithm, and a truncated fingerprint for each key.

Shell completions

Generate shell completion scripts for tab-completion support.


credat completions bash     # generate bash completions
credat completions zsh      # generate zsh completions
credat completions fish     # generate fish completions
credat completions install  # show install instructions for your shell

Installation example (zsh):


credat completions zsh > ~/.zsh/completions/_credat

Global options

Option	Description
`--json`	Output structured JSON (works with all commands that produce output)
`-V, --version`	Show CLI and SDK versions
`-h, --help`	Show help

The `.credat/` directory

The CLI stores all state in a .credat/ directory in your current working directory:

File	Contents
`agent.json`	Agent identity (DID, key pair, DID Document)
`owner.json`	Owner key pair
`delegation.json`	The signed delegation token
`status-list.json`	Revocation status list (created by `credat revoke`)

Security: The .credat/ directory contains private keys. Add it to .gitignore and never commit it to version control.

Relationship to the SDK

The CLI is a thin wrapper around the Credat SDK. Every CLI command maps to SDK functions:

CLI command	SDK function
`credat init`	`createAgent()`
`credat delegate`	`delegate()`
`credat verify`	`verifyDelegation()`
`credat inspect`	Manual JWT decode (no single SDK function)
`credat revoke`	`createStatusList()`, `setRevocationStatus()`, `isRevoked()`
`credat audit`	Custom analysis of token claims
`credat renew`	`delegate()` (re-issues with new expiry)
`credat handshake challenge`	`createChallenge()`
`credat handshake present`	`presentCredentials()`
`credat handshake verify`	`verifyPresentation()`
`credat keys export/import`	`publicKeyToJwk()`, `jwkToPublicKey()`
`credat demo`	Full handshake flow

For programmatic usage, use the SDK directly. The CLI is best for prototyping, demos, and quick verification tasks.

CLI Reference

Installation

Quick start

Commands

credat init

credat delegate

credat verify [token]

credat inspect [token]

credat revoke

credat audit [token]

credat renew

credat status

credat demo