@usesigillum/cli

Sigillum is an x402-powered risk oracle for autonomous agents and developer workflows.

The public CLI is hosted-first:

npx @usesigillum/cli inspect --git-diff

By default, the CLI targets https://usesigillum.vercel.app. Localhost remains available through --base-url or env overrides for internal development.

Quick Start

Get a real price without paying first:

npx @usesigillum/cli quote --git-diff

Then run the live inspection:

Inspect the current git diff:

npx @usesigillum/cli inspect --git-diff

Inspect a diff file:

npx @usesigillum/cli inspect ./change.patch

Quote a diff before paying:

npx @usesigillum/cli quote --git-diff

Save a receipt locally:

npx @usesigillum/cli inspect --git-diff --save-receipt ./sigillum-receipt.json

Emit machine-readable output:

npx @usesigillum/cli inspect --git-diff --json

Hosted Use

Hosted use should not require a local Next.js app.

Default API target order:

1. --base-url
2. SIGILLUM_BASE_URL or X402_API_BASE_URL
3. hosted default: https://usesigillum.vercel.app

Minimum common envs for live x402 use:

SIGILLUM_PAYMENT_MODE=x402
X402_BUYER_PRIVATE_KEY=0x...
X402_NETWORK=arcTestnet
X402_RPC_URL=https://rpc.testnet.arc.network

Live hosted x402 use still depends on a buyer-side payment key today. The CLI does not hide that requirement.

That means the current hosted contract is:

• quote works without buyer payment credentials
• inspect requires buyer-side x402 payment credentials
• the buyer-side Gateway balance is the thing that must be ready for repeated paid runs

Optional:

X402_BUYER_AUTO_DEPOSIT_USDC=1.0
SIGILLUM_MAX_QUOTE_AMOUNT_USDC=0.000500

That env only matters if you want the buyer-side Gateway balance to auto-top-up during a real paid flow. SIGILLUM_MAX_QUOTE_AMOUNT_USDC gives solo builders a simple spend ceiling before Sigillum pays through x402.

If you prefer to cap spend per run instead of through env, pass:

npx @usesigillum/cli inspect --git-diff --max-quote-amount 0.000500

Two-Minute Onboarding

1. Run quote --git-diff first and make sure the amount looks acceptable.
2. Add buyer-side live envs only when you are ready to pay for inspect.
3. Check balances if payment readiness is unclear:

npm.cmd run x402:buyer:balance
npm.cmd run x402:seller:balance

4. If the buyer Gateway balance is low, either:

• set X402_BUYER_AUTO_DEPOSIT_USDC and rerun a real paid inspect flow
• or top up the buyer Gateway balance before retrying

Troubleshooting

• Buyer private key is required for the x402 payment flow. Set X402_BUYER_PRIVATE_KEY or SIGILLUM_BUYER_PRIVATE_KEY.
• No current git diff found. Make a tracked change first, or pass a diff file path explicitly.
• Could not reach the Sigillum API... Check --base-url, SIGILLUM_BASE_URL, or X402_API_BASE_URL.
• x402 payment flow failed because the buyer wallet nonce is behind the network state. Wait for the previous Arc testnet transaction to settle, or use a fresh funded buyer key, then retry.
• Quote amount ... exceeds the configured maximum ... Lower the change surface, raise SIGILLUM_MAX_QUOTE_AMOUNT_USDC, or pass a higher --max-quote-amount.

Commands

• inspect <diff-path>
• inspect --git-diff
• quote <diff-path>
• quote --git-diff
• --json
• --save-receipt <path>
• --fail-on-warn
• --base-url <url>
• --max-quote-amount <usdc>

Exit Codes

• 0 pass, or warn when --fail-on-warn is not set
• 1 warn when --fail-on-warn is set
• 2 block
• 3 infrastructure, config, input, or payment-flow error