# 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](/docs/selling), for agents see [agents.md](/docs/agents). Every command is in
[CLI.md](/docs/cli).

## 1. Install

You need Node.js 22.22.2 or newer.

```sh
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](/docs/overview#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:

```sh
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](#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:

```sh
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

```sh
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.

```sh
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.

```sh
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.

```sh
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](/docs/cli).

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

```sh
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`:

```sh
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:

```ts
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](/docs/sdk). It approves and pays this storage deposit.

Details on NEAR storage: [near-accounts.md](/docs/near-accounts). If something goes wrong:
[what-can-go-wrong.md](/docs/what-can-go-wrong).
