CLI reference

CLI reference

The Boon CLI is the agent-native surface for approved USDC thank-yous. It uses a small funded OWS wallet, local guardrails, dry-runs, and explicit approvals before live sends.

Source of truth: cli/src/index.ts.

Commands

Command	Purpose
boon doctor	Check local settings, OWS wallet readiness, Base RPC, contract, USDC balance, and guardrails.
boon doctor --json	Print machine-readable readiness output for agents.
boon wallet connect ows --wallet <name>	Select the OWS wallet Boon should use for agent sends.
boon wallet current	Show selected OWS address and Base USDC balance.
boon wallet current --json	Print machine-readable wallet status.
boon wallet disconnect	Forget Boon’s selected OWS wallet.
boon tip <handle> <amount-usdc> <note>	Send a boon through the connected OWS wallet.
boon tip --dry-run <handle> <amount-usdc> <note>	Validate, canonicalize, check guardrails, and preview without moving funds.
boon tip --json --dry-run ...	Machine-readable dry-run output for agent review.
boon tip --yes --approval-id <id> ...	Execute without interactive prompt only when a human-approved policy or plan id authorizes the exact send.
boon history [handle]	Show local send history, optionally filtered by canonical handle.
boon weekly	Print the weekly agent review workflow entry point.

First OWS setup

boon wallet connect ows --wallet boon-agent
boon wallet current
boon doctor

Fund the printed OWS address with a small amount of Base USDC plus gas headroom, then run boon doctor again.

Dry-run before send

boon tip --dry-run github:alice 5 "pr:owner/repo#42 — review"

The dry-run should show:

• canonical handle and handle hash
• Base mainnet and deployed Boon contract
• USDC amount in token units
• note
• current local spend/cooldown status
• whether the command would approve USDC before calling Boon.tip(...)

Live send

Interactive operator-approved send:

boon tip github:alice 5 "pr:owner/repo#42 — review"

Agent-policy send:

boon tip --yes --approval-id weekly-2026-05-25 github:alice 5 "pr:owner/repo#42 — review"

--yes is intentionally gated by --approval-id. The id should refer to a human-approved policy or plan that allows the exact tip within the funded wallet’s caps.

Local files

Boon stores local CLI state under ~/.boon/:

File	Meaning
settings.json	Contract, USDC, RPC, API/app URLs, selected OWS wallet alias/address.
config.json	Guardrail caps such as per-day spend, per-tip max, cooldown, and CI dry-run behavior.
spend-log.json	Local spend total and most recent tip timestamp for guardrail checks.
history.jsonl	Local successful-tip ledger.

Do not commit .boon/ files. They may contain addresses, handles, notes, and operational state.

Defaults

Default guardrails are intentionally small:

{
  "maxUsdcPerDay": "50",
  "maxUsdcPerTip": "10",
  "minSecondsBetweenTips": 60,
  "dryRunInCi": true
}

The CLI is for Base USDC only and calls the deployed Boon contract. It does not accept arbitrary token addresses or non-Base chains.