Commands
Every command is the same on npx bitplan and bunx bitplan.
Publish a draft. bunx bitplan works the same.
Skip the default 1Sat notification for this upload.
Optional label, shown in list and My drafts.
Publish the next version for this wallet and these readers.
Save a default reader for new plans.
Save a public wallet key under a local name.
Add a saved contact to a local team.
Drafts this wallet holds.
Check the wallet and print its identity key.
Decrypt HTML to stdout.
Print the installed CLI version.
Flags
| Command | Flags |
|---|---|
| upload <file> | --draft <origin>, --new, --description <text>, --share-with <identity-key|contact|team>, --private, --link, --hosted, --no-relay, -y, --json, --allow-finding <id> |
| inscribe <h_id|file> | --all-versions, --wallet-url <url>, --site-url <url>, -y, --json |
| list | --json, -v/--verbose, --limit <n> |
| fetch <origin|url> | --meta, --json, --version <n> |
| auth / whoami | --wallet-url <url>, --json on whoami |
| config | --share-with <identity-key|contact|team>, --clear-share-with |
| contact | set <name> <identity-key>, remove <name>, list [--json] |
| team | set <name> <contacts...>, add <name> <contacts...>, remove <name> <contacts...>, delete <name>, list [name] [--json] |
| version | prints the installed CLI version |
| catalog sync | --json, --wallet-url <url>, --site-url <url> |
--share-with is repeatable and additive, up to 128 readers. It publishes one encrypted document plus a small wallet-wrapped key per identity. --private makes only the new version wallet-only; older shared versions cannot be revoked. Shared drafts require CLI 0.0.6+ or the current website to read.
--link: Add a reader link anyone can open; kept on later versions until --private. When adopting without local state, a new link is additive because earlier link slots cannot be distinguished from other inherited readers.
--hosted stores the sealed envelope on bitplan.dev instead of the chain, so no BSV is needed. Add --link when someone should be able to read without a wallet. The complete link is a bearer credential: anyone who has it can read. bitplan inscribe <h_id|file> publishes the latest version on chain; --all-versions replays the whole history.
Run bunx bitplan catalog sync to retry the catalog sync and merge locally tracked drafts when the automatic sync was skipped or failed. A second device with the same BRC-100 wallet identity can list and read those hosted plans, but it cannot update them.
--share-with accepts a public identity key, contact, or team. config --share-with saves the choice as a default for new plans. Use config --clear-share-with to clear it.
Contact names, their public keys, and team membership are defined in ~/.bitplan/config.json. A local draft may remember a name so it can resolve the current members when you publish. Neither names nor membership go to BitPlan servers or on-chain; only public identity keys appear in the shared envelope. BitPlan has no accounts or team directory. Hosted storage contains sealed envelopes, not contact names, team membership, wallet keys, or plaintext.
Removing a team member excludes them from the next version of locally tracked plans that remember that team. It cannot remove access to versions already shared with them.
fetch --meta writes metadata to stderr, including whether the envelope is private or shared and the public reader list. HTML remains on stdout so it can be redirected to a file.
Agents and scripts can use upload --yes --json or fetch --json to receive one JSON value. JSON output never counts as permission to publish; upload still requires the explicit --yes flag and wallet approval.
By default, upload sends the wallet-returned Atomic BEEF to 1Sat after publishing. 1Sat attempts to capture it for OrdFS and forwards the transaction to Arcade, which can make the viewer available sooner. Relay failure is a warning; it does not undo the wallet publish. Pass --no-relay to opt out.
On-chain bytes are documented in the envelope spec.