Command Reference - Beltic Docs

Complete reference documentation for all Beltic CLI commands. For workflow tutorials, see CLI Workflows.

Global Options

Available for all commands:

Option	Description
`--help`, `-h`	Show help information
`--version`, `-V`	Show version information

beltic init

Initialize a new agent manifest with interactive or non-interactive prompts.

Synopsis

beltic init [OPTIONS]

Options

Option	Type	Description	Default
`--output`, `-o`	path	Output file path	`agent-manifest.json`
`--config`, `-c`	path	Config file path	`.beltic.yaml`
`--include`, `-i`	pattern	Include pattern (repeatable)	From config
`--exclude`, `-e`	pattern	Exclude pattern (repeatable)	From config
`--type`, `-t`	enum	Deployment type	`standalone`
`--developer-id`	uuid	Developer credential ID	Prompted
`--force`, `-f`	flag	Overwrite existing file	`false`
`--non-interactive`	flag	Skip prompts, use defaults	`false`
`--no-validate`	flag	Skip validation (scaffolding only)	`false`

Deployment Types: standalone, monorepo, embedded, plugin, serverless

Examples

Interactive (default):

beltic init

Non-interactive with custom output:

beltic init --non-interactive --output my-manifest.json

Monorepo with specific patterns:

beltic init \
  --type monorepo \
  --include "packages/agent/**" \
  --exclude "**/node_modules/**"

Force overwrite:

beltic init --force --output existing-manifest.json

Exit Codes

0 - Success
1 - Validation failed
2 - File write error
3 - Configuration error

beltic fingerprint

Generate or verify SHA256 fingerprint of codebase and update manifest.

Synopsis

beltic fingerprint [OPTIONS]

Options

Option	Type	Description	Default
`--manifest`, `-m`	path	Manifest file path	`agent-manifest.json`
`--config`, `-c`	path	Config file path	`.beltic.yaml`
`--deps`, `-d`	flag	Include dependency fingerprints	`false`
`--verify`, `-v`	flag	Verify without writing	`false`
`--verbose`	flag	Show all files processed	`false`

Examples

Basic fingerprint generation:

beltic fingerprint

Verify without modifying:

beltic fingerprint --verify

Include dependencies:

beltic fingerprint --deps

Verbose output:

beltic fingerprint --verbose

Custom manifest:

beltic fingerprint --manifest custom-manifest.json

Exit Codes

0 - Success (or fingerprints match in verify mode)
1 - Fingerprints mismatch (verify mode)
2 - File read/write error
3 - Configuration error

beltic keygen

Generate Ed25519 (EdDSA) or P-256 (ES256) cryptographic keypairs in PKCS#8 PEM format.

Synopsis

beltic keygen --algorithm <ALG> --output <PATH> [OPTIONS]

Options

Option	Type	Description	Required
`--algorithm`, `--alg`, `-a`	enum	Signature algorithm	Yes
`--output`, `--out`, `-o`	path	Private key output path	Yes
`--pub`, `-p`	path	Public key output path	Auto-generated

Algorithms: EdDSA, ES256 Note: Public key filename is automatically generated as {output}.pub.pem unless --pub is specified.

Examples

EdDSA (recommended):

beltic keygen --algorithm EdDSA --output private.pem
# Creates: private.pem and private.pub.pem

ES256 with custom public key path:

beltic keygen --algorithm ES256 --output key.pem --pub pubkey.pem

Short form:

beltic keygen -a EdDSA -o key.pem

Security Notes

Private keys are cleared from memory after writing
Files are created with restrictive permissions (600)
Keys are in PKCS#8 PEM format

Exit Codes

0 - Success
1 - Key generation failed
2 - File write error

beltic sign

Sign AgentCredential or DeveloperCredential payloads as JWS tokens with Beltic media types.

Synopsis

beltic sign --payload <PATH> --key <PATH> [OPTIONS]

Options

Option	Type	Description	Required
`--payload`, `-p`	path	Credential JSON file	Yes
`--key`, `-k`	path	Private key PEM file	Yes
`--algorithm`, `--alg`, `-a`	enum	Signature algorithm	Auto-detect from key
`--output`, `--out`, `-o`	path	Output JWS token file	Stdout
`--kid`	string	Key ID (DID URL)	Optional
`--issuer`, `-i`	did	Issuer DID	From payload
`--subject`, `-s`	did	Subject DID	From payload
`--audience`, `-aud`	did	Audience DID	Optional
`--credential-type`	enum	Force credential type	Auto-detect
`--skip-schema`	flag	Skip schema validation	`false`

Algorithms: EdDSA, ES256 Credential Types: agent, developer

Examples

Basic signing:

beltic sign --payload credential.json --key private.pem --output token.jwt

With all options:

beltic sign \
  --payload agent-credential.json \
  --key agent-key.pem \
  --algorithm EdDSA \
  --output agent.jwt \
  --kid did:web:example.com#key-1 \
  --issuer did:web:issuer.beltic.dev \
  --subject did:web:agent.example.com \
  --audience did:web:platform.example.com

Agent credential (subject required):

beltic sign \
  --payload agent.json \
  --key key.pem \
  --subject did:web:agent.example.com

Skip schema validation (debugging only):

beltic sign --payload test.json --key key.pem --skip-schema

JWT Structure

Header:

{
  "alg": "EdDSA",
  "typ": "application/beltic-agent+jwt",
  "kid": "did:web:example.com#key-1"
}

Payload:

{
  "iss": "did:web:issuer.beltic.dev",
  "sub": "did:web:subject.example.com",
  "jti": "credential-id",
  "iat": 1699876800,
  "nbf": 1699876800,
  "exp": 1731412800,
  "aud": "did:web:platform.example.com",
  "vc": { /* Full credential object */ }
}

Exit Codes

0 - Success
1 - Schema validation failed
2 - Signing failed
3 - File read/write error

beltic verify

Verify JWS signature, JWT claims, and credential schema.

Synopsis

beltic verify --token <TOKEN> --key <PATH> [OPTIONS]

Options

Option	Type	Description	Required
`--token`, `-t`	path/string	JWS token (file or string)	Yes
`--key`, `-k`	path	Public key PEM file	Yes
`--issuer`, `-i`	did	Expected issuer DID	Optional
`--audience`, `-aud`	did	Expected audience DID	Optional
`--credential-type`	enum	Force credential type	Auto-detect
`--skip-schema`	flag	Skip schema validation	`false`

Examples

Basic verification:

beltic verify --token credential.jwt --key public.pem

From token string:

beltic verify --token "eyJhbGci..." --key public.pem

With issuer constraint:

beltic verify \
  --token credential.jwt \
  --key public.pem \
  --issuer did:web:issuer.beltic.dev

With issuer and audience:

beltic verify \
  --token credential.jwt \
  --key public.pem \
  --issuer did:web:issuer.beltic.dev \
  --audience did:web:platform.example.com

Verification Steps

Parse JWT - Decode header, payload, signature
Signature - Verify cryptographic signature
Claims - Validate iss, sub, exp, nbf, aud
Schema - Validate credential against JSON schema

Output

Success:

✓ Signature valid
✓ Claims valid
✓ Schema valid

Credential Details:
  ID: credential-id
  Subject: did:web:subject.example.com
  Issuer: did:web:issuer.beltic.dev
  Issued: 2025-01-15T00:00:00Z
  Expires: 2026-01-15T00:00:00Z

VALID

Failure:

✗ Signature verification failed
INVALID: Signature does not match public key

Exit Codes

0 - Valid
1 - Invalid signature
2 - Invalid claims
3 - Schema validation failed
4 - File read error

beltic dev-init

Create a self-attested DeveloperCredential for use with agent credentials. This command generates a minimal DeveloperCredential that identifies you as the developer of AI agents.

Synopsis

beltic dev-init [OPTIONS]

Options

Option	Type	Description	Default
`--output`, `-o`	path	Output file path	`developer-credential.json`
`--name`	string	Legal name (person or organization)	Prompted
`--entity-type`	enum	Entity type	Prompted
`--country`	string	Country code (ISO 3166-1 alpha-2)	Prompted
`--website`	url	Website URL	Prompted
`--email`	email	Business email address	Prompted
`--public-key`	path	Public key PEM to embed	Auto-discovered
`--force`, `-f`	flag	Overwrite existing file	`false`
`--non-interactive`	flag	Skip prompts, use defaults	`false`

Entity Types: individual, corporation, limited_liability_company, sole_proprietorship, partnership, nonprofit, government_agency

Examples

Interactive (recommended):

beltic dev-init

Non-interactive with all options:

beltic dev-init \
  --name "Acme AI Solutions Inc." \
  --entity-type corporation \
  --country US \
  --website https://acme.ai \
  --email dev@acme.ai \
  --public-key public.pem \
  --output developer-credential.json \
  --non-interactive

For individual developer:

beltic dev-init \
  --name "Jane Developer" \
  --entity-type individual \
  --country US \
  --non-interactive

Output

Creates a self-attested DeveloperCredential JSON file:

{
  "credentialId": "550e8400-e29b-41d4-a716-446655440000",
  "legalName": "Acme AI Solutions Inc.",
  "entityType": "corporation",
  "incorporationJurisdiction": { "country": "US" },
  "kybTier": "tier_0_unverified",
  "issuanceDate": "2025-01-15T00:00:00Z",
  "expirationDate": "2025-04-15T00:00:00Z",
  ...
}

Exit Codes

0 - Success
1 - Validation failed
2 - File write error
3 - Missing required fields (non-interactive mode)

beltic http-sign

Sign HTTP requests per RFC 9421 for Web Bot Auth compatibility. This command generates the required Signature-Agent, Signature-Input, and Signature headers.

Synopsis

beltic http-sign --method <METHOD> --url <URL> --key <PATH> --key-directory <URL> [OPTIONS]

Options

Option	Type	Description	Required
`--method`, `-m`	enum	HTTP method (GET, POST, etc.)	Yes
`--url`, `-u`	url	Target URL	Yes
`--key`, `-k`	path	Ed25519 private key (PEM)	Yes
`--key-directory`	url	URL to agent’s key directory	Yes
`--header`, `-H`	string	Additional header (repeatable)	No
`--component`	string	Signature component (repeatable)	Default set
`--body`, `-b`	string	Request body string	No
`--body-file`	path	Request body from file	No
`--expires-in`	int	Signature validity in seconds	`60`
`--format`, `-f`	enum	Output format	`headers`

Methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS Formats: headers, curl Default Components: @method, @authority, @path, signature-agent

Examples

Sign a GET request:

beltic http-sign \
  --method GET \
  --url https://api.example.com/data \
  --key private.pem \
  --key-directory https://myagent.example.com/.well-known/http-message-signatures-directory

Sign a POST request with body:

beltic http-sign \
  --method POST \
  --url https://api.example.com/submit \
  --key private.pem \
  --key-directory https://myagent.example.com/.well-known/http-message-signatures-directory \
  --body '{"data": "value"}'

Output as curl command:

beltic http-sign \
  --method GET \
  --url https://api.example.com/data \
  --key private.pem \
  --key-directory https://myagent.example.com/.well-known/http-message-signatures-directory \
  --format curl

Include custom headers:

beltic http-sign \
  --method POST \
  --url https://api.example.com/data \
  --key private.pem \
  --key-directory https://myagent.example.com/.well-known/http-message-signatures-directory \
  --header "Content-Type: application/json" \
  --body-file request.json

Output

Headers format (default):

Signature-Agent: "https://myagent.example.com/.well-known/http-message-signatures-directory"
Signature-Input: sig1=("@method" "@authority" "@path" "signature-agent");alg="ed25519";keyid="S9Zz0...";created=1735689600;expires=1735689660;nonce="abc123";tag="web-bot-auth"
Signature: sig1=:jdq0SqOwHdyHr9+r5jw3iYZ...==:

Curl format:

curl -X GET "https://api.example.com/data" \
  -H 'Signature-Agent: "https://myagent.example.com/.well-known/http-message-signatures-directory"' \
  -H 'Signature-Input: sig1=...' \
  -H 'Signature: sig1=:...:' 

Exit Codes

0 - Success
1 - Key read error
2 - Signing failed
3 - Invalid URL or method

beltic directory

Commands for managing key directories for HTTP Message Signatures (Web Bot Auth).

beltic directory generate

Generate a key directory JSON file from public keys.

Synopsis

beltic directory generate --public-key <PATH> --out <PATH> [OPTIONS]

Options

Option	Type	Description	Required
`--public-key`, `-p`	path	Public key PEM (repeatable)	Yes
`--out`, `-o`	path	Output path for directory JSON	Yes
`--sign`	flag	Also output signature headers	No
`--private-key`	path	Private key for signing (with —sign)	With —sign
`--authority`	string	Authority for signature (with —sign)	With —sign

Examples

Generate basic key directory:

beltic directory generate \
  --public-key public.pem \
  --out .well-known/http-message-signatures-directory

With multiple keys:

beltic directory generate \
  --public-key key1-public.pem \
  --public-key key2-public.pem \
  --out directory.json

With signed response headers:

beltic directory generate \
  --public-key public.pem \
  --out directory.json \
  --sign \
  --private-key private.pem \
  --authority myagent.example.com

Output

Key Directory JSON:

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "base64url-encoded-public-key"
    }
  ]
}

beltic directory thumbprint

Compute the JWK thumbprint for a public key.

Synopsis

beltic directory thumbprint --public-key <PATH>

Options

Option	Type	Description	Required
`--public-key`, `-p`	path	Public key PEM	Yes

Examples

beltic directory thumbprint --public-key public.pem

Output

S9Zz0KJG8h_vY5nZq1aH3Xw2bP4...

The thumbprint is the JWK thumbprint (RFC 7638) used as the keyid in HTTP Message Signatures.

Exit Codes (directory commands)

0 - Success
1 - Key read error
2 - File write error
3 - Invalid key format

Environment Variables

Variable	Description	Default
`BELTIC_CONFIG`	Default config file path	`.beltic.yaml`
`BELTIC_MANIFEST`	Default manifest file path	`agent-manifest.json`
`RUST_LOG`	Log level (error, warn, info, debug, trace)	`warn`

Example

export BELTIC_CONFIG=.beltic.production.yaml
export RUST_LOG=debug
beltic init

Common Patterns

Complete Developer Credential Workflow

# 1. Copy template
cp beltic-spec/examples/developer/v1/tests/valid-individual-minimal.json dev.json

# 2. Validate
ajv validate -s beltic-spec/schemas/developer/v1/developer-credential-v1.schema.json -d dev.json

# 3. Generate keys
beltic keygen -a EdDSA -o dev-key.pem

# 4. Sign
beltic sign -p dev.json -k dev-key.pem -o dev.jwt --kid did:web:example.com#key-1

# 5. Verify
beltic verify -t dev.jwt -k dev-key.pub.pem

Complete Agent Credential Workflow

# 1. Initialize manifest
beltic init

# 2. Generate fingerprint
beltic fingerprint

# 3. Generate keys
beltic keygen -a ES256 -o agent-key.pem

# 4. Sign
beltic sign -p agent-manifest.json -k agent-key.pem -s did:web:agent.example.com -o agent.jwt

# 5. Verify
beltic verify -t agent.jwt -k agent-key.pub.pem

Overview

Getting started

Credentials

CLI

TypeScript SDK

Python SDK

Examples

Advanced

Reference

​Global Options

​beltic init

​Synopsis

​Options

​Examples

​Exit Codes

​beltic fingerprint

​Synopsis

​Options

​Examples

​Exit Codes

​beltic keygen

​Synopsis

​Options

​Examples

​Security Notes

​Exit Codes

​beltic sign

​Synopsis

​Options

​Examples

​JWT Structure

​Exit Codes

​beltic verify

​Synopsis

​Options

​Examples

​Verification Steps

​Output

​Exit Codes

​beltic dev-init

​Synopsis

​Options

​Examples

​Output

​Exit Codes

​beltic http-sign

​Synopsis

​Options

​Examples

​Output

​Exit Codes

​beltic directory

​beltic directory generate

​Synopsis

​Options

​Examples

​Output

​beltic directory thumbprint

​Synopsis

​Options

​Examples

​Output

​Exit Codes (directory commands)

​Environment Variables

​Example

​Common Patterns

​Complete Developer Credential Workflow

​Complete Agent Credential Workflow

​See Also

Global Options

beltic init

Synopsis

Options

Examples

Exit Codes

beltic fingerprint

Synopsis

Options

Examples

Exit Codes

beltic keygen

Synopsis

Options

Examples

Security Notes

Exit Codes

beltic sign

Synopsis

Options

Examples

JWT Structure

Exit Codes

beltic verify

Synopsis

Options

Examples

Verification Steps

Output

Exit Codes

beltic dev-init

Synopsis

Options

Examples

Output

Exit Codes

beltic http-sign

Synopsis

Options

Examples

Output

Exit Codes

beltic directory

beltic directory generate

Synopsis

Options

Examples

Output

beltic directory thumbprint

Synopsis

Options

Examples

Output

Exit Codes (directory commands)

Environment Variables

Example

Common Patterns

Complete Developer Credential Workflow

Complete Agent Credential Workflow

See Also