Beltic CLI

​

Core capabilities

• Agent manifest management (interactive or non-interactive)
• Deterministic SHA256 fingerprinting with include/exclude patterns
• Key generation for Ed25519 (EdDSA) and P-256 (ES256)
• Schema-aware signing (Agent/Developer credentials) into JWTs with Beltic media types
• Verification with signature, claims, and JSON Schema validation
• HTTP Message Signatures (RFC 9421) for Web Bot Auth
• Key directory generation and management

​

Install

​

Quick Install (Recommended)

brew tap belticlabs/tap
brew install beltic

curl -fsSL https://raw.githubusercontent.com/belticlabs/beltic-cli/master/install.sh | sh

​

Build from Source

git clone https://github.com/belticlabs/beltic-cli.git
cd beltic-cli
cargo build --release
./target/release/beltic --help

cargo install --path .

​

Quick start (end-to-end)

# 1) Initialize an agent manifest
beltic init

# 2) Generate a SHA256 fingerprint
beltic fingerprint

# 3) Generate keys
beltic keygen --alg EdDSA --out private-key.pem --pub public-key.pem

# 4) Sign the manifest
beltic sign --key private-key.pem --payload agent-manifest.json --out credential.jwt

# 5) Verify the signature
beltic verify --key public-key.pem --token credential.jwt

​

Command reference

​

init

• Interactive or non-interactive manifest creation.
• Options: --output, --config, --include, --exclude, --type (standalone, monorepo, embedded, plugin, serverless), --developer-id, --force, --non-interactive, --no-validate.
• Notes: uses .beltic.yaml templates; can run without validation for scaffolding.

​

dev-init

• Create a self-attested DeveloperCredential.
• Options: --output, --name, --entity-type, --country, --website, --email, --public-key, --force, --non-interactive.
• Notes: generates a minimal DeveloperCredential for self-signing workflows.

​

fingerprint

• Generates or verifies the SHA256 fingerprint and updates the manifest by default.
• Options: --manifest, --config, --deps (include dependency fingerprints), --verify (do not write), --verbose.
• Notes: --verify lets you compare hashes without mutating the manifest.

​

keygen

• Generates Ed25519 (EdDSA) or P-256 (ES256) keypairs in PKCS#8 PEM.
• Options: --alg, --out (private key path), --pub (public key path).
• Notes: clears secrets from memory after writing keys.

​

sign

• Signs AgentCredential or DeveloperCredential payloads as JWTs with Beltic media types and a vc claim.
• Options: --key, --alg, --payload, --out, --kid, --issuer, --subject, --audience, --credential-type, --skip-schema.
• Output: compact JWT with typ of application/beltic-agent+jwt or application/beltic-developer+jwt.
• Notes: --credential-type forces detection; --skip-schema is only for debugging.

​

verify

• Verifies signature plus issuer/audience/time claims and validates the vc claim against schemas.
• Options: --key, --token, --issuer, --audience, --credential-type, --skip-schema.
• Output: VALID with decoded payload on success; INVALID with error detail otherwise.
• Notes: accepts token from file or inline string; supports expected issuer/audience filters.

​

http-sign

• Signs HTTP requests per RFC 9421 for Web Bot Auth compatibility.
• Options: --method, --url, --key, --key-directory, --header, --body, --body-file, --expires-in, --format.
• Output: signature headers or curl command.

​

directory generate

• Generates a key directory JSON for HTTP Message Signatures.
• Options: --public-key, --out, --credential-url, --sign, --private-key, --authority.

​

directory thumbprint

• Computes the JWK thumbprint for a public key.
• Options: --public-key.

​

Developer credential workflow (CLI)

# Create a self-attested developer credential
beltic dev-init --name "Jane Developer" --entity-type individual --country US

# Generate keys and sign
beltic keygen --alg EdDSA --out dev-key.pem --pub dev-key.pub.pem
beltic sign \
  --key dev-key.pem \
  --payload developer-credential.json \
  --out developer-credential.jwt \
  --kid did:web:example.com#dev-key-1

# Verify the credential
beltic verify --key dev-key.pub.pem --token developer-credential.jwt

​

Agent credential workflow (CLI)

# Initialize and fingerprint an agent manifest
beltic init --output agent-manifest.json
beltic fingerprint --manifest agent-manifest.json

# Sign the agent credential
beltic keygen --alg ES256 --out agent-key.pem --pub agent-key.pub.pem
beltic sign \
  --key agent-key.pem \
  --payload agent-credential.json \
  --out agent-credential.jwt \
  --kid did:web:example.com#agent-key-1 \
  --subject did:web:agent.example.com

# Verify with issuer/audience expectations
beltic verify \
  --key agent-key.pub.pem \
  --token agent-credential.jwt \
  --issuer did:web:example.com

​

Web Bot Auth workflow (CLI)

# Generate keys
beltic keygen --alg EdDSA --out private.pem --pub public.pem

# Generate key directory (with optional credential URL)
beltic directory generate \
  --public-key public.pem \
  --credential-url https://your-agent.com/credential.jwt \
  --out .well-known/http-message-signatures-directory

# Sign HTTP requests
beltic http-sign \
  --method POST \
  --url https://api.example.com/action \
  --key private.pem \
  --key-directory https://your-agent.com/.well-known/http-message-signatures-directory \
  --body '{"action": "transfer"}' \
  --format curl

​

Configuration quick notes

version: "1.0"
agent:
  paths:
    include:
      - "src/**"
      - "package.json"
    exclude:
      - "**/*.test.*"
      - "**/node_modules/**"
  deployment:
    type: "standalone"

​

Examples

• Test agent: beltic-cli/test-agent/ is a TypeScript customer support agent demonstrating init, fingerprint, keygen, sign, and verify.
• Sample CLI workflows live in beltic-cli/README.md (standalone and serverless examples).
• Credential templates align with the spec repo fixtures under beltic-spec/examples/* so you can sign and verify realistic payloads.

​

Related

• CLI Installation
• Command Reference
• Web Bot Auth