Start · Quick start: buy a file from the command line
Quick start: buy a file from the command line
This page sets up the annon CLI, buys a file, opens it, and gets it back on another computer. For
selling see selling.md, for agents see agents.md. Every command is in
CLI.md.
1. Install
You need Node.js 22.22.2 or newer.
npm install -g @defdone/annon@alpha
The packages are on the npm alpha tag. If npm reports no matching version right after a release,
retry with npm i -g @defdone/annon@alpha --prefer-online. To use a build from source instead (see
Build and test), run node packages/annon/dist/node/main.js in place
of annon.
2. Configure
Annon is an open protocol and any team can run a deployment. The quickest start uses the one run by defdone. Run:
annon init --deployment defdone
It does two things and prints where each file is:
- If nothing exists yet at
~/.config/annon/config.json(or the file named by--configorANNON_CONFIG), it writes the configuration for the deployment run by defdone there. It never changes, replaces or writes through anything already at that path; init says it kept it. - It creates the backup secret that encrypts your local purchase records (below).
Plain annon init in a terminal asks the same question: "Use the Annon deployment run by defdone
(...)? [Y/n]". Enter or yes writes the configuration; no writes none and prints this page's link.
Without a terminal and without --deployment, init writes no configuration and says how to add one.
This is the configuration it writes. stateDir is set to the absolute path of
~/.local/share/annon. To use another deployment, write your own file in the same shape:
{
"contractId": "v1.annon.defdone.near",
"network": "near:mainnet",
"nearRpc": "https://rpc.mainnet.fastnear.com",
"relayer": "https://relayer.mainnet.annon.dev",
"stateDir": "/absolute/path/to/annon-state",
"maxPrice": "0.10",
"shops": [
{
"id": "demo",
"manifest": "https://annon.dev/.well-known/annon-shop.json",
"profile": {
"network": "near:mainnet",
"contract": "v1.annon.defdone.near",
"nearRpc": "https://rpc.mainnet.fastnear.com",
"relayer": "https://relayer.mainnet.annon.dev",
"host": "https://demo.annon.dev"
}
}
],
"defaultShop": "demo"
}
maxPrice is the most a single purchase may cost, in USDC. To pay on Base, also add "baseRpc"
(Pay on Base), and add the same "baseRpc" to the demo shop's profile.
The shops entry adds the demo shop, so annon catalog lists its files and annon buy 2 buys row
2. Its profile is your approval of the deployment the shop uses: annon share uploads only to a
shop with a profile that matches this configuration, and stops with trust_required without one or
config_conflict when a value differs.
The same annon init creates the backup secret that encrypts your local purchase records. It writes
32 random bytes to ~/.config/annon/backup-secret, readable only by you, and prints where
the file is. It never prints the secret and never replaces an existing file: run it again and it only
checks the file. Other commands read the file but never create it. To keep the secret somewhere
else, point ANNON_BACKUP_SECRET_FILE at that file instead.
Back up the file now, separately from your records, to private encrypted storage you have mounted. This copies it without displaying it and refuses to overwrite an existing copy:
node --input-type=module -e '
import { constants } from "node:fs";
import { copyFile } from "node:fs/promises";
await copyFile(process.argv[1], process.argv[2], constants.COPYFILE_EXCL);
' "$HOME/.config/annon/backup-secret" /mounted-private-encrypted-backup/annon-backup-secret
Check that the copy has mode 600. If a copy already exists, keep it and choose another name. Encrypted record backups in your state directory do not include this secret.
Keep this secret and your purchase IDs. With them you can check, resume and open a purchase. If you lose the secret, your saved records cannot be decrypted, but the same wallet can still recover the file (step 5).
3. Sign in with your wallet
annon login --wallet near # or: annon login --wallet evm
Login opens a local page in your browser and proves you control the wallet. It installs no key. Every payment is approved in the wallet. For NEAR, pick Meteor Wallet or HOT Wallet on the page; MyNearWallet no longer connects to apps.
4. Buy and open
Check the file, buy it, wait until the purchase is accepted, and open it. Pick the path that matches
where your money is. In a terminal the CLI answers in short text and buy waits for acceptance
itself; with --json, or when its output is piped, every command prints the JSON envelope and
returns at once, except buy --open <file>, which waits for acceptance and writes the file.
Run annon with no arguments to work in one session instead: it keeps running until you type
exit, the commands need no annon prefix, catalog numbers a shop's files and buy 2 buys row 2
and asks where to save it.
Each path starts with login; skip it if you already signed in with that
wallet in step 3. Login remembers one wallet, so sign in again to switch.
--trust-contractrecords once that you trust this contract to release keys.buyshows the price, the recipients and the route, and asks before it pays. It prints the purchase ID.- Your purchase is saved, encrypted, before you pay. If
statussayspending, or a command stops withsettlement_pending(exit code 4), wait and check again; resume the same purchase withannon statusandannon openinstead of starting a new one. While it is live or accepted, a secondannon buyof the same file is refused withpurchase_openunless you pass--force. - If
buyends withstate: "uncertain"(exit code 4), the wallet may have sent the payment. Do not pay again: runannon statuswith the purchase ID until it saysaccepted. annon statusandannon open --output <file>without an ID use your latest purchase for the configured contract and network. The ID of a purchase saved for that contract and network can be shortened to its first 8 or more hex digits.
Pay on NEAR
You need a NEAR wallet with USDC on NEAR and a little NEAR for gas.
annon login --wallet near
annon verify https://demo.annon.dev/f/what-we-are-building --trust-contract
annon buy https://demo.annon.dev/f/what-we-are-building --route near --open what-we-are-building.pdf
You approve the USDC transfer in your wallet. --open waits until NEAR accepts the purchase and
writes the decrypted file. Without it, or if acceptance takes longer than three minutes (exit code
4), finish with annon status and annon open --output what-we-are-building.pdf.
Pay on Base
You need an EVM wallet with USDC on Base. No ETH: you sign a USDC authorization and the host submits
it. First add "baseRpc" to your config, with a Base RPC endpoint that has an API key: the CLI reads
the Base payment through it, and the public endpoint rate-limits those reads.
annon login --wallet evm
annon verify https://demo.annon.dev/f/what-we-are-building --trust-contract
annon buy https://demo.annon.dev/f/what-we-are-building --route base
annon status 0xPURCHASE_ID
annon open 0xPURCHASE_ID --output file.pdf
Until the payment reaches Safe finality on Base and NEAR has verified it, status can report
pending or return settlement_pending (exit code 4). Wait for retryAfterSeconds when provided,
then run it again until it says accepted. Then open writes the decrypted file.
This route works only for a file whose on-chain terms include a Base payee; only files from EVM
sellers can have one. For any other file, buy --route base stops with
route_unavailable before any wallet or payment step; pay it with 1Click from Base instead.
Pay from another chain with 1Click
You need a supported token on the source chain, plus that chain's gas. The quote includes the swap fees.
annon login --wallet evm
annon verify https://demo.annon.dev/f/what-we-are-building --trust-contract
annon buy https://demo.annon.dev/f/what-we-are-building --route 1click --from-chain base
annon status 0xPURCHASE_ID
annon open 0xPURCHASE_ID --output what-we-are-building.pdf
buy returns deposit instructions: an address, an amount in the token's base units, the asset, a
memo if one is needed, and depositBefore. Send exactly that amount to that address, with the memo
if required, from your own wallet. The deposit must be confirmed on the source chain before
depositBefore; allow time for confirmation and do not fund an expired quote. Then run status
until it says accepted; a 1Click SUCCESS alone is not acceptance. open writes the decrypted file.
For another chain, change --from-chain (for example arbitrum, ethereum, polygon or
solana). Without --from-asset, the CLI selects USDC only when 1Click lists exactly one USDC
asset for that chain. For another token, or if it returns origin_asset_required, pass
--from-asset with the exact 1Click nep141: asset ID. Source-chain refunds go to your signed-in
wallet when it is on the same kind of chain. Otherwise, or to get refunds at the wallet you pay
from, add --refund-to with an address on the source chain. Supported chains and options:
CLI.md.
5. Open it on another computer
With your saved secret. Copy the backup-secret file securely into a private directory on the new
computer (directory mode 700, file mode 600), and copy your encrypted purchase backups separately. Do not run annon init
first; select the restored file instead. The variable holds a path, not the secret:
export ANNON_BACKUP_SECRET_FILE=/absolute/private/restored-annon-backup-secret
annon open /absolute/private/purchase-backup.json --url https://host.example/file --output restored-file
Opening one known backup proves the restore worked. You can also restore it to
~/.config/annon/backup-secret: create ~/.config/annon with mode 700, then run the copy command
from step 2 with the two paths swapped, so the saved copy is the source and the default path the
destination.
With a fresh secret. The same wallet gets the file again without paying a second time. Repeat
steps 1 to 3 on the new computer, including annon init, then recover and open. annon init creates
a new secret only when both your stateDir and ~/.local/share/annon hold no records or backups,
because a new secret cannot decrypt them. If old ones are there, first move the whole old state,
including ~/.local/share/annon, to a separate private archive and keep it. The example below uses a NEAR account; for an
EVM wallet, replace near:YOUR_ACCOUNT.near with evm:0xYOUR_ADDRESS:
annon recover --recovery near:YOUR_ACCOUNT.near
annon open 0xPURCHASE_ID --url https://demo.annon.dev/f/what-we-are-building --output what-we-are-building.pdf
An EVM or Solana wallet can recover through the relayer without paying NEAR. A NEAR account funds
storage for its new key grant. Before recover, use the SDK's storageDeposit with your NEAR wallet
and an amount you choose, for example 0.01 NEAR:
import { storageDeposit } from '@defdone/annon';
await storageDeposit(nearWallet, 'v1.annon.defdone.near', 10_000_000_000_000_000_000_000n);
nearWallet is your NEAR transaction wallet in the SDK, for example nearKeyPairWallet(account) as
in the SDK README. It approves and pays this storage deposit.
Details on NEAR storage: near-accounts.md. If something goes wrong: what-can-go-wrong.md.