Beltic logo
CLI Guide

Beltic CLI

Manage manifests, fingerprints, signing, and verification from the terminal

The Beltic CLI issues and verifies Beltic credentials with deterministic code fingerprints and cryptographic signatures. It is the fastest path to creating AgentCredential and DeveloperCredential tokens from a local codebase.

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

Homebrew (macOS/Linux):

brew tap belticlabs/tap
brew install beltic

Shell script:

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

Build from Source

Requires Rust 1.70+ (2021 edition).

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

Or install locally:

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

All commands accept --help for full usage.

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

The CLI reads .beltic.yaml to control fingerprinting and deployment metadata:

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

Deployment types include standalone, monorepo, embedded, plugin, and serverless. See .beltic.yaml.example in beltic-cli for richer templates.

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.

Credential Lifecycle

Complete lifecycle from manifest submission through issuance, verification, updates, and revocation.

CLI Installation

Install and set up the Beltic CLI for credential management and verification.

On this page

Core capabilitiesInstallQuick Install (Recommended)Build from SourceQuick start (end-to-end)Command referenceinitdev-initfingerprintkeygensignverifyhttp-signdirectory generatedirectory thumbprintDeveloper credential workflow (CLI)Agent credential workflow (CLI)Web Bot Auth workflow (CLI)Configuration quick notesExamplesRelated