CLI Reference

The CCP CLI provides full control over the containment certificate lifecycle. Published as @iamnotdou/ccp on npm.

Installation

npm install -g @iamnotdou/ccp

Usage

ccp <command> [options]

For AI agents, the MCP server is recommended — see AI Agent Integration.

Certificate Commands

status

Display full system overview: reserve balance, spending limits, cosigner status, and configuration.

cert:get <certHash>

Retrieve certificate details by hash. Shows: operator, agent, class, containment bound, status, issued/expires dates, auditors.

cert:lookup <agentAddress>

Find the active certificate for a given agent address. Returns the certificate hash.

cert:verify <agentAddress>

Verify that an agent meets containment requirements. Checks: certificate validity, reserve adequacy, spending limit configuration, auditor attestations.

cert:valid <certHash>

Simple boolean check: is this certificate currently valid?

cert:publish

Publish a new certificate. Full flow: generates cert hash, collects operator + auditor signatures, calls CCPRegistry.publish().

cert:revoke <certHash>

Revoke a certificate. Operator-only action. Sets status to REVOKED.

Reserve Commands

reserve:status

Show reserve vault status: balance, stated amount, lock status, adequacy check.

reserve:deposit <amount>

Deposit USDC into the reserve vault. Amount in whole USDC (e.g., 150000).

reserve:lock <days>

Lock the reserve for a specified number of days. Cannot withdraw while locked.

Spending Commands

spending:status

Show spending limit status: current period spent, remaining allowance, configuration, cosigner address.

spending:pay <to> <amount>

Execute a payment through SpendingLimit. Agent signature only. Fails if amount exceeds cosign threshold.

spending:pay:cosign <to> <amount>

Execute a payment with Ledger co-signature. Required for amounts above the cosign threshold ($5,000).

Auditor Commands

auditor:status [address]

Show auditor information: total attestations, successful challenges, active stake. Defaults to configured auditor if no address given.

auditor:audit

Run a containment audit. Checks all constraint surfaces and reports findings.

auditor:attest <certHash>

Full attestation flow: run audit, lock stake, sign attestation. Combines audit + stake + sign in one command.

Challenge Commands

challenge:get <id>

Get challenge details by ID: type, challenger, bond, status, evidence hash, resolution.

challenge:list <certHash>

List all challenges filed against a certificate.

HCS Commands

hcs:timeline

Display the HCS event timeline. Fetches events from Hedera Mirror Node and displays them chronologically.

hcs:create-topic

Create a new HCS topic for CCP events.

Utility Commands

addresses

Display all deployed contract addresses (Registry, SpendingLimit, ReserveVault, AuditorStaking, FeeEscrow, ChallengeManager, USDC).

actors

Display all actor addresses (Operator, Agent, Auditor, Ledger).

help

Show the help message with all available commands.

Environment Variables

The CLI reads configuration from a .env file in the agent/ directory: