annon
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.

Shell
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:

Shell
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 --config or ANNON_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:

JSON
{
  "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:

Shell
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

Shell
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-contract records once that you trust this contract to release keys.
  • buy shows 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 status says pending, or a command stops with settlement_pending (exit code 4), wait and check again; resume the same purchase with annon status and annon open instead of starting a new one. While it is live or accepted, a second annon buy of the same file is refused with purchase_open unless you pass --force.
  • If buy ends with state: "uncertain" (exit code 4), the wallet may have sent the payment. Do not pay again: run annon status with the purchase ID until it says accepted.
  • annon status and annon 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.

Shell
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.

Shell
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.

Shell
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:

Shell
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:

Shell
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:

TypeScript
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.

Synced from docs/quickstart.md at commit e649de1. Also asMarkdown.