@spoolis/cli

Spoolis CLI

Turn an agreement into verifiable acceptance criteria, verify fulfillment, and determine what was earned. Use Spoolis when payment depends on whether work actually passed.

The CLI compiles, creates, reads, and verifies Spools. It can also run the no-account demo flow.

Install

npm i -g @spoolis/cli

Set up an API key

Create a key at spoolis.com/dashboard/api-keys, then set it in your environment:

export SPOOLIS_API_KEY="your-key"

The CLI uses https://spoolis.com by default. Set SPOOLIS_API_URL to use another Spoolis API host.

Examples

Run the signed sandbox loop without an API key. Set SPOOLIS_BASE_URL to use another sandbox host.

spoolis demo

Compile text and review grounded terms, suggested conditions, and questions separately:

spoolis compile "A buyer pays for 100 enrichment records at $1.00 per accepted record, total $100.00."

Create a Spool. Suggested conditions are never included automatically. Add only the conditions you choose:

spoolis create "A buyer pays for 100 enrichment records at $1.00 per accepted record, total $100.00." \
  --condition "Provide exactly 100 enrichment records"

Read a human summary or the raw canonical JSON:

spoolis get spl_123
spoolis get spl_123 --json

Read the event history with human labels and canonical event names:

spoolis events spl_123

Run verification using the evidence already submitted to the Spool:

spoolis verify outcome-receipt.json

Repository source also supports a consumer policy with --require. It verifies the receipt first, then requires the selected result, agreement, issuer, age, unit, earned-value, evidence-completeness, per-condition (required_conditions), uncertainty-cap (max_uncertain_units), or acceptance-ratio (min_accepted_ratio) constraints:

spoolis verify outcome-receipt.json --require '{"minimum_status":"pass","evidence_requirements":"satisfied"}'

--require ships in @spoolis/cli 0.1.5 and later. Forward supersession cannot be known from an offline receipt; use the hosted status endpoint when current correction or revocation state matters.

Start new receipt integrations with the one-call verify quickstart, then use the CLI to verify the returned receipt offline.

For the bilateral receipt flow, compile the 100-record purchase, verify the delivery, read the signed receipt for 98 accepted and 2 rejected records with $98.00 earned, verify the receipt offline, optionally add --strict to check GET /api/v1/receipts/{id}/status, then let the payment stack act on the earned amount. Offline signature verification remains sufficient.

Find API key management instructions:

spoolis keys

Scope

This release covers text compilation and creation, Spool reads, event history, verification, and the sandbox demo loop. Outside the demo command, it does not create API keys, submit evidence, or manage the full Spool lifecycle. It sends no telemetry and has no runtime dependencies.