@attocash/cli 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +173 -817
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,947 +1,303 @@
1
1
  # Atto CLI
2
2
 
3
- **An Atto wallet for your terminal.**
3
+ Create an Atto wallet, send payments, and receive funds from your terminal.
4
+ Name your addresses, follow activity live, or use JSON output in scripts.
4
5
 
5
- **Beta** · [Install from npm](https://www.npmjs.com/package/@attocash/cli)
6
-
7
- Create a wallet, name your addresses, and send payments from the command line.
8
- Check what arrived, follow activity live, or use JSON output in your own scripts.
9
- Available as an initial beta for macOS, Linux, and Windows.
10
-
11
- This guide follows the current source checkout. Published npm releases may lag
12
- behind it, including Marketplace commands. Check your installed `atto --help`
13
- and command-specific help, or [build from source](#install-from-source) to use
14
- the checkout's features. See the [repository release status](https://github.com/attocash/integrations#release-status).
6
+ **Beta** · [`@attocash/cli` on npm](https://www.npmjs.com/package/@attocash/cli) ·
7
+ macOS, Linux, and Windows
15
8
 
16
9
  [Install](#install) · [Set up a wallet](#set-up-the-wallet) ·
17
- [Everyday examples](#everyday-examples) · [Command reference](#use-the-cli) ·
18
- [Recovery](#profiles-and-recovery)
19
-
20
- - **Readable destinations.** Send to personal names such as “Savings”.
21
- - **Live activity.** Watch incoming payments and keep automatic receiving running.
22
- - **Scriptable results.** Use `--json` for structured output and durable request IDs for retries.
23
- - **An optional agent companion.** Connect [Atto MCP](https://www.npmjs.com/package/@attocash/mcp)
24
- to a separate wallet or share this one with approved spending limits.
10
+ [Everyday examples](#everyday-examples) · [Automation](#use-the-cli) ·
11
+ [Recovery](#profiles-and-recovery) ·
12
+ [Full reference](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md)
25
13
 
26
14
  ## Install
27
15
 
28
- Requires **Node.js 24.15.0 or newer**. Use the latest 24.x release. Install from npm:
16
+ Requires **Node.js 24.15.0 or newer** and an accessible OS password store:
17
+
18
+ | OS | Password-store prerequisite |
19
+ | --- | --- |
20
+ | macOS | Keychain access for the CLI |
21
+ | Linux | `secret-tool` (usually `libsecret-tools`), an unlocked Secret Service provider such as GNOME Keyring or KWallet, and access to its D-Bus session |
22
+ | Windows | Credential Manager access for the CLI |
29
23
 
30
24
  ```sh
31
25
  npm install --global @attocash/cli
32
26
  atto --help
33
27
  ```
34
28
 
35
- Omitting a package version installs the latest compatible release. You can
36
- also run commands without a global installation; `@latest` explicitly selects
37
- the current published release:
29
+ Or run without a global installation:
38
30
 
39
31
  ```sh
40
32
  npx --yes @attocash/cli@latest --help
41
33
  ```
42
34
 
43
- To install both the CLI and MCP server globally:
44
-
45
- ```sh
46
- npm install --global @attocash/cli @attocash/mcp
47
- ```
48
-
49
- Linux also requires `secret-tool` (usually the `libsecret-tools` package), an
50
- unlocked Secret Service provider such as GNOME Keyring or KWallet, and access to
51
- your desktop D-Bus session. macOS uses Keychain; Windows uses Credential Manager.
52
- An unavailable password store is an error; there is no plaintext file fallback.
35
+ The executable is `atto`. There is no plaintext recovery-phrase fallback when
36
+ the password store is unavailable. Headless Linux environments need a working
37
+ Secret Service session too; check it with `atto doctor`.
53
38
 
54
39
  ## Set up the wallet
55
40
 
56
- Create a wallet in your own interactive terminal:
41
+ Run this in your own interactive terminal:
57
42
 
58
43
  ```sh
59
44
  atto wallet create
60
45
  ```
61
46
 
62
- Setup stores the recovery phrase in your OS password store and displays it in
63
- the terminal. Keep a private offline copy. If you already have a recovery
64
- phrase, run `atto wallet import` instead; it asks for the phrase through a
65
- hidden prompt.
47
+ Creation stores the recovery phrase in your OS password store before displaying
48
+ it. **Keep a private offline copy.** To restore an existing phrase, use
49
+ `atto wallet import` instead; it asks through a hidden prompt. Creation, import,
50
+ and `atto wallet backup` require a terminal and never accept recovery words as
51
+ command arguments, JSON, or environment variables.
66
52
 
67
- Find your address and check your balance:
53
+ Find your receiving address and check the wallet:
68
54
 
69
55
  ```sh
70
56
  atto address list
57
+ atto wallet status
71
58
  atto balances
72
59
  ```
73
60
 
74
- The default network is LIVE. To receive incoming payments, leave this command
75
- running in a terminal:
61
+ The default network is **LIVE**. Send funds to your listed address from another
62
+ wallet, and keep this command running to receive incoming payments:
76
63
 
77
64
  ```sh
78
65
  atto wallet receive
79
66
  ```
80
67
 
81
- It reports incoming payments and confirmed receives as they happen. Stop it
82
- with Ctrl+C. Use `atto doctor` if you need help checking your environment.
68
+ It reports pending payments and confirmed receives. Stop it with Ctrl+C.
69
+ Finite commands such as `balances` exit after their operation; they do not keep
70
+ receiving in the background.
83
71
 
84
72
  ## Everyday examples
85
73
 
86
- ### Put names next to your addresses
74
+ ### Send to a personal name
75
+
76
+ With a funded account 0, create a second receiving address, name it, and send
77
+ 1 ATTO to it:
87
78
 
88
79
  ```sh
89
- atto labels set 0 "Main"
90
- atto labels list
91
- atto balances
80
+ atto address activate 1
81
+ atto labels set 1 "Savings"
82
+ atto send --to-label "Savings" --amount 1 --request-id savings-001
92
83
  ```
93
84
 
94
- Labels appear beside full addresses in wallet output. They belong to your
95
- profile and network, and can also name external recipients.
96
-
97
- ### Move funds to “Savings”
98
-
99
- With a funded wallet, this example activates address 1, gives it a personal
100
- name, and sends 1 ATTO there from address 0:
85
+ `--to-label` matches a personal name exactly, ignoring case. The CLI shows the
86
+ full destination and request ID before network work. To pay an external address,
87
+ replace `RECIPIENT_ADDRESS` with its full Atto address:
101
88
 
102
89
  ```sh
103
- atto address activate 1
104
- atto labels set 1 "Savings"
105
- atto send --to-label "Savings" --amount 1
90
+ atto send RECIPIENT_ADDRESS 1.25 --request-id invoice-42
106
91
  ```
107
92
 
108
- The CLI shows the resolved address and request ID. Keep that ID if the payment
109
- is interrupted; it identifies the same payment when you retry.
110
- [Personal names and retry behavior](#address-labels-and-personal-name-payments).
93
+ Amounts are exact decimal strings; the default unit is `ATTO`. `--unit RAW`
94
+ selects raw units. The source defaults to account 0; `--index 1` selects another
95
+ saved account. The source must hold the full amount unless you explicitly use
96
+ an approved [account pool](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#use-the-cli).
111
97
 
112
- ### Follow activity or use it in a script
98
+ ### Check payments and activity
113
99
 
114
100
  | Task | Command |
115
101
  | --- | --- |
116
- | Recent payments | `atto history --limit 10` |
117
- | Incoming payment events | `atto watch receivable` |
118
- | Balances as JSON | `atto --json balances` |
102
+ | Recent payment activity | `atto history --limit 10` |
103
+ | Pending incoming payments | `atto receivables --limit 10` |
104
+ | Observe incoming payment events | `atto watch receivable` |
105
+ | Receive a batch for account 0 | `atto receive-all --index 0` |
106
+ | All saved address balances | `atto balances --all` |
119
107
  | Saved payment attempts | `atto journal list --limit 10` |
120
- | Environment diagnostics | `atto doctor` |
121
-
122
- Watching incoming payments only observes them. Run `atto wallet receive` when
123
- you want the wallet to receive them automatically.
124
108
 
125
- ### Fund a Marketplace account
126
-
127
- Connect the wallet from an interactive local terminal using the Marketplace
128
- `/v1/agent/topups` URL, its exact controller-proof audience, and a saved wallet
129
- account. The connection uses the existing wallet key for authentication; session
130
- tokens stay in memory. HTTPS is required except for loopback HTTP on an isolated
131
- LOCAL wallet.
109
+ `watch` observes events; it does not receive funds. Use `wallet receive` for
110
+ continuous receiving across active addresses.
132
111
 
133
- ```sh
134
- atto address derive 1
135
- atto marketplace connect --api-url https://<marketplace-host>/v1/agent/topups --audience <agent-api-audience> --controller-index 1 --browser-origin https://<site-host>
136
- atto marketplace topup 1 --unit ATTO --request-id marketplace-funding-2026-001
137
- atto marketplace status marketplace-funding-2026-001
138
- ```
139
-
140
- `--browser-origin` may be repeated for up to eight exact origins. The CLI binds
141
- browser proof approvals to that provisioned list; it does not accept an origin
142
- from an approval file as configuration. Without this option, only the Marketplace
143
- API origin is allowed. Cross-origin browser login and protected actions require
144
- an existing local Marketplace connection. For an isolated LOCAL stack, use its exact
145
- loopback API and site origins, for example `http://localhost:8080` and
146
- `http://localhost:5173`; loopback HTTP is rejected for non-LOCAL wallets.
147
-
148
- ```sh
149
- atto marketplace connect --api-url http://localhost:8080/v1/agent/topups --audience <agent-api-audience> --controller-index 1 --browser-origin http://localhost:5173
150
- ```
151
-
152
- Marketplace top-ups use the existing shared spending limits, approved account pool,
153
- and wallet journal. Keep the printed request ID and reuse it after an uncertain
154
- result; status and recovery use the same intent and exact signed native payment.
155
- An unresolved top-up keeps its account frontier and allowance reserved. This
156
- flow funds the configured Marketplace account only. It does not create tasks, hire
157
- agents, or submit work. The MCP `marketplace_topup` and `marketplace_topup_status` tools
158
- become available after a local terminal connection; spending still requires
159
- approved MCP access.
160
-
161
- ### Review a Marketplace wallet approval
112
+ ### Resume an interrupted payment
162
113
 
163
- When Marketplace provides a local wallet approval command, run it in your own
164
- interactive terminal with the selected wallet's `--data-dir` and the exact
165
- request-file path it supplies:
114
+ Keep the original payment details and request ID:
166
115
 
167
116
  ```sh
168
- atto --data-dir /absolute/path/to/profile marketplace approve /path/to/handoff/0123456789abcdef0123456789abcdef.request.json
117
+ atto journal show invoice-42
118
+ atto send RECIPIENT_ADDRESS 1.25 --request-id invoice-42
169
119
  ```
170
120
 
171
- Review the Marketplace origin, controller, purpose, expiry, and action details,
172
- then type `approve` only if they match your intended action. The CLI validates
173
- the typed challenge and signs its exact message, then writes a private sibling
174
- `<handoff-id>.response.json` file for Marketplace to consume. Keep the original
175
- file paths; an existing response is never overwritten. Expired challenges
176
- require a new request.
177
-
178
- File-based approval requires POSIX file-ownership support and is unavailable on
179
- native Windows.
180
-
181
- This local review does not require or grant unattended message-signing access.
182
- For product purchase and refund approvals, the preview distinguishes proof-bound
183
- terms from client-provided seller, buyer, fee, and net details that the proof does
184
- not verify.
121
+ The original ID checks the recorded payment and resumes its existing progress.
122
+ An uncertain publication reuses the exact signed transaction. Conflicting reuse
123
+ is rejected. **A new request ID means a new payment.** If you omit
124
+ `--request-id`, the CLI generates one and prints it before starting; retain it.
185
125
 
186
126
  ## Use the CLI
187
127
 
188
- Run `atto` to see the available commands. Incomplete command groups such as
189
- `atto wallet`, and invalid commands or options, show an error and the relevant
190
- help on stderr. Explicit `--help` and bare `atto` print help on stdout and exit
191
- successfully. With `--json`, parser errors remain structured JSON on stdout.
192
-
193
- Amounts are exact decimal strings. The default unit is `ATTO`; use `--unit RAW`
194
- for raw amounts. `atto send` generates a unique request ID and displays it before
195
- starting. Use `--request-id` to supply your own or check a previous payment.
196
- **Running the command again without its original ID creates a new payment.**
197
-
198
- Temporary connection failures, timeouts, and HTTP 5xx responses retry automatically
199
- with delays of 1, 2, 4, 8, 16, then 30 seconds until success or Ctrl+C. HTTP 4xx
200
- responses (including 429), invalid responses, and local validation or policy errors
201
- stop the command. Retrying publication checks for confirmation first and otherwise
202
- resends the identical signed transaction; it never builds another debit.
203
-
204
- Ctrl+C stops further attempts. An in-flight Commons node request finishes or times
205
- out before shutdown; a payment may already have reached the node. Keep the request
206
- ID and inspect `atto journal show <request-id>` before starting another payment.
207
- Reusing an unresolved payment's ID checks its recorded transaction; it does not
208
- construct a replacement payment.
209
- With `--json`, stdout contains one result/error envelope; request ID and retry
210
- progress are JSON lines on stderr. Error details include the request ID.
211
- MCP and generic `atto call send` still require a caller-supplied ID and do not
212
- automatically retry.
213
-
214
- ```sh
215
- atto account --index 0
216
- atto account <atto-address>
217
- atto balances --addresses <address-1>,<address-2>
218
- atto send <destination> 1.25
219
- atto send --to-index 1 --amount 1
220
- atto send --to-label "Savings" --amount 1
221
- atto send <destination> 1 --index 1 --request-id invoice-from-account-1
222
- atto send <destination> 100 --unit RAW --request-id invoice-2026-002
223
- atto send <destination> 1 --request-id order-42 --reason 'Invoice 42' --metadata '{"orderId":"42"}'
224
- atto pool status
225
- atto journal list --status unknown --limit 20
226
- atto journal show order-42
227
- atto quote --usd 1
228
- atto metrics
229
- atto receivables --limit 100
230
- atto receive <send-hash> --index 0
231
- atto receive-all --index 0
232
- atto representative change <atto-address> --index 0
233
- atto representative weight <atto-address>
234
- atto transaction <hash>
235
- atto entry <hash>
236
- atto history transaction --addresses <atto-address> --from-height 1 --limit 50
237
- atto history --index 0
238
- atto history entry --addresses <atto-address> --cursor <returned-cursor>
239
- atto watch account --addresses <atto-address>
240
- atto watch receivable --addresses <atto-address> --min-amount-raw 1
241
- atto watch transaction --network-wide
242
- ```
243
-
244
- To send 1 ATTO from account 0 to saved account 1, use
245
- `atto send --to-index 1 --amount 1`. The destination must already be saved;
246
- `--to-index` does not derive it. Choose a destination address, `--to-index`, or `--to-label`,
247
- and use `--amount` or `--usd` with index/name targets. Each send generates its request ID
248
- when omitted; retain the printed ID for retries.
249
-
250
- `atto send` uses index `0` by default. Use `--index N` to select another derived
251
- account, or `--pool` to select automatically from the approved account pool.
252
- `--pool` and `--index` are mutually exclusive. Default and explicit source
253
- accounts must hold the full payment amount. The initial pool contains index `0`,
254
- with consolidation disabled. MCP selects from the approved pool when its `index`
255
- is omitted; explicit MCP indexes must also belong to that pool.
256
-
257
- Configure the pool in your own terminal:
258
-
259
- ```sh
260
- atto pool configure --indexes 0,1,2
261
- # Allow sends using --pool to combine balances from these accounts:
262
- atto pool configure --indexes 0,1,2 --consolidate
263
- ```
264
-
265
- This preserves the spending limits and MCP access mode, displays the exact pool
266
- change, and requires local approval. Omitted pool settings are preserved; `--no-consolidate` disables consolidation. Pool
267
- indexes must be unique, between `0` and `2147483647`, with at most 100 members.
268
- Approval derives missing indexes without activating them for automatic receiving.
269
- `pool status` reports balances, available totals, and account readiness.
270
-
271
- Pool selection prefers an available account with enough funds and valid work for
272
- its current account head. Public work is prepared when a spending session starts and
273
- after confirmed account mutations, and cached in the shared profile. Account
274
- locks allow independent accounts to send concurrently across CLI/MCP processes
275
- using that same local profile; unfinished payments keep their accounts reserved.
276
-
277
- When consolidation is approved, a payment using `--pool` may first move funds
278
- among verified wallet-owned pool accounts, then make one payment to the destination.
279
- Only the final payment consumes the spending allowance. Consolidation applies
280
- only to automatic pool selection (`--pool` for `atto send`). Spending limits and
281
- pool approval are checked again
282
- before each planned signature; a partially completed payment can pause until its
283
- remaining steps are authorized again. Retain `--pool` and the original request ID
284
- to resume confirmed progress. An unresolved block remains reserved until canonical network
285
- evidence establishes its outcome.
286
-
287
- ```sh
288
- atto send <destination> 2 --pool --request-id pooled-invoice-2026-001
289
- # Retry that same payment after an interruption:
290
- atto send <destination> 2 --pool --request-id pooled-invoice-2026-001
291
- ```
292
-
293
- `--metadata` accepts a JSON object of up to 4096 UTF-8 bytes with bounded nesting;
294
- `--reason` adds `metadata.reason`. Supplying the reason twice is rejected.
295
- Metadata stays in the local payment journal and is never published on the Atto
296
- network. Treat it as caller-supplied text and keep secrets out of it. A retry
297
- retains the original metadata when omitted; changed metadata for the same request
298
- ID is rejected.
299
-
300
- `journal list` returns newest records first, with an optional `--status` of
301
- `reserved`, `signed`, `published`, `unknown`, or `failed`. Use the returned
302
- `nextCursor` as `--cursor` with the same status filter; `--limit` accepts 1–100
303
- and defaults to 50. `journal show` reads one request's metadata, source, network,
304
- and recorded payment progress.
305
-
306
- USD-priced sends use an indicative market conversion. Read the terms, record
307
- your explicit acceptance of their current version, then send:
308
-
309
- ```sh
310
- atto terms show
311
- atto terms accept --version <displayed-version> --accepted
312
- atto send --destination <atto-address> --usd 1 --request-id invoice-2026-003
313
- # Equivalent amount/unit form:
314
- atto send <atto-address> 1 --unit USD --request-id invoice-2026-004
315
- ```
316
-
317
- USD sends are available on LIVE. Market data is dated daily, and conversions
318
- reject observations older than 72 hours. Amounts round down to whole RAW.
319
- The returned price and timestamp describe an indicative valuation;
320
- they do not guarantee an executable exchange price. No exchange trade is made.
321
- A USD send fixes its Atto amount for that request ID, so retries do not reprice
322
- the payment. Budget consumption always uses the resulting Atto amount. Reading
323
- metrics and previewing a quote do not require accepting terms.
324
-
325
- `history` defaults to action-oriented account entries; use `history transaction`
326
- when you need raw signed protocol records, including receive-block `sendHash`
327
- linkage. Entries include the account owner's `address`, `subjectAddress`, and
328
- `subjectRole`:
329
-
330
- | Entry action | Subject role | Subject address |
331
- |---|---|---|
332
- | `SEND` | `receiver` | Payment destination |
333
- | `OPEN`, `RECEIVE` | `sender` | Account that sent the payment |
334
- | `CHANGE` | `representative` | Newly selected voter |
335
-
336
- Transfers also include an exact `amount` with `raw` and `atto` decimal strings,
337
- calculated from the entry's balance change. Representative changes have no
338
- transfer amount. Existing protocol fields remain available.
339
-
340
- Use `atto account --addresses <address-a>,<address-b>` for full account snapshots
341
- including height, balance, and representative. JSON results contain
342
- `accounts: [{address, account}]`, with `account: null` for an unopened address.
343
- The existing `atto account <address>` and `atto account --index 0` forms retain
344
- their single `account` result.
345
-
346
- Node requests automatically use batches of **5** for the official
347
- `gatekeeper.<network>.application.atto.cash` URLs (`live`, `beta`, or `dev`),
348
- and **1,000** for other node URLs. A smaller selection is sent in one
349
- request. This is a client query setting; direct nodes do not impose the
350
- gateway's five-account limit.
351
-
352
- Override it for a custom gateway or node, or restore automatic selection:
128
+ Inspect commands and options locally:
353
129
 
354
130
  ```sh
355
- atto wallet configure --node-batch-size 5
356
- atto wallet configure --node-batch-size 1000
357
- atto wallet configure --node-batch-size auto
131
+ atto --help
132
+ atto send --help
133
+ atto wallet --help
358
134
  ```
359
135
 
360
- The override is saved in this profile and applies to account snapshots, balances,
361
- history, and account/receivable watches. Entry/transaction watches retain
362
- per-account subscriptions for their replay checkpoints. Custom gateways and
363
- proxies require an explicit override when their limit differs from the
364
- custom-node default.
365
- `wallet status` shows the override and effective size. The tool's existing
366
- 100-address selection limit and 1,000-record history page limit still apply.
367
-
368
- History, receivables, balances, and watches default to active wallet addresses.
369
- Use `--index N` or `--addresses <address,...>` to select saved or external accounts;
370
- these selectors cannot be combined. Watches also accept `--network-wide` for
371
- account, transaction, and entry events, or `--hash` for one transaction or entry.
372
- These scopes are mutually exclusive. Watches only observe events and report
373
- connection status even when no events arrive; they do not start receiving.
374
-
375
- List commands return bounded results and explain when the scan window or record
376
- limit was reached. `history` and `journal list` support continuation cursors with
377
- the same filters; `receivables` does not support cursors. History also supports
378
- inclusive height ranges. Watch output reports retention gaps; account and
379
- receivable streams do not guarantee replay of every transition.
380
-
381
- `receive <hash>` receives one payment. `receive-all` processes a bounded batch
382
- for account 0 by default (`--index N` selects another account). Run it again if
383
- more remain, or use `wallet receive` for continuous receiving across active
384
- accounts. Continuous receiving requires an initialized wallet, enabled automatic
385
- receiving, and at least one active account.
386
-
387
- CLI commands print readable text by default, including when piped. Wallet import
388
- and creation show a confirmation and address; balances, payments, history, and
389
- watches show labeled values. Addresses, amounts, hashes, and cursors are never
390
- rounded or shortened. Wallet status omits internal fingerprints and public keys.
391
- Payment and network summaries show exact ATTO and RAW amounts, addresses, and
392
- transaction hashes. Human output omits signatures, work, and serialized blocks;
393
- `--json` includes the complete protocol data. Local payment metadata stays visible.
394
-
395
- Use `--json` whenever you want the complete structured result, especially in
396
- scripts. This applies to every command, including `call` and streaming watches:
136
+ Readable text is the default, including when piped. For automation, pass `--json`:
397
137
 
398
138
  ```sh
399
- atto wallet status
400
- atto --json wallet status
401
139
  atto --json balances
402
- atto --json journal list
140
+ atto --json history --limit 10
141
+ atto --json send RECIPIENT_ADDRESS 1.25 --request-id invoice-42
403
142
  ```
404
143
 
405
- In JSON mode, success is
406
- `{"result": ...}`; operational failure is
407
- `{"error":{"code":"...","message":"..."}}` and a nonzero exit status.
408
- Each response is one compact JSON line. Existing scripts that parsed the old
409
- default pretty-printed JSON must now pass `--json`. MCP response formats are unchanged.
410
- Without `--json`, failures and cancellations are readable messages on stderr.
411
- Cancelling a prompt exits with status `1` and leaves the wallet unchanged.
412
- Large protocol integers remain strings. Invalid CLI arguments return a sanitized
413
- `INVALID_INPUT` error; use command-specific `--help` for accepted arguments.
414
- Dependency diagnostics go to stderr.
415
-
416
- Single operations are available through the CLI's generic adapter. Inspect an
417
- operation's input schema before constructing its JSON:
144
+ Single commands write one compact `{"result": ...}` envelope to stdout.
145
+ Failures use `{"error":{"code":"...","message":"..."}}` and a nonzero exit
146
+ status. Large protocol integers remain strings. Send progress and retry messages
147
+ go to stderr as JSON lines; watch and receiving commands stream multiple result
148
+ lines. Doctor also returns a result envelope when a check fails, with exit status 1.
418
149
 
419
- ```sh
420
- atto operations
421
- atto operations send
422
- atto --json call account_get --input '{"index":0}'
423
- atto --json call history_list --input '{"event":"entry","limit":50}'
424
- ```
150
+ `atto send` retries temporary connection failures, timeouts, and HTTP 5xx errors
151
+ with delays up to 30 seconds until success or Ctrl+C. HTTP 4xx errors, including
152
+ 429, and validation or policy errors stop the command. An in-flight request may
153
+ finish after Ctrl+C; inspect the journal and reuse its ID before paying again.
154
+ Automation should retain request IDs and account for potentially long retries.
425
155
 
426
- Generic `atto call send` follows the shared operation schema: omitting `index`
427
- selects from the approved pool. Include `"index": 0` to select account zero.
428
-
429
- `atto watch` keeps its session open and streams events directly. Generic
430
- `call watch_*` commands are rejected because their session would end immediately;
431
- use MCP for persistent watch IDs and cursor-based polling.
156
+ For schema-based integrations, use `atto operations`, `atto operations send`,
157
+ and `atto --json call account_get --input '{"index":0}'`. Generic `call send`
158
+ requires a request ID and does not automatically retry. See the
159
+ [command and JSON reference](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#use-the-cli)
160
+ and [wallet engine API](https://github.com/attocash/integrations/blob/main/docs/library-api.md).
432
161
 
433
162
  ## Diagnostics
434
163
 
435
- Run doctor in the environment where the failure happens:
164
+ Run diagnostics in the environment where the failure occurs:
436
165
 
437
166
  ```sh
438
167
  atto doctor
439
168
  atto --json doctor
440
169
  atto --data-dir /absolute/path/to/profile doctor
441
- atto-mcp --data-dir /absolute/path/to/profile doctor
442
- # Run MCP diagnostics without a global installation:
443
- npx --yes @attocash/mcp@latest --data-dir /absolute/path/to/profile doctor
444
170
  ```
445
171
 
446
- Both commands run full checks by default. Allow up to 60 seconds. The OS password
447
- store may ask you to unlock it or allow credential access, and the worker receives
448
- one fresh proof-of-work request. Doctor verifies the recovery phrase against the
449
- saved wallet identity inside a separate process; it never prints or returns the
450
- phrase, seed, or private key. Nothing is signed, published, or added to the work
451
- cache. Doctor does not start receiving or retry pending payments.
452
-
453
- The report includes:
454
-
455
- - Runtime and package versions, executable, selected profile, credential service
456
- and account, configured node and worker URLs.
457
- - Public-state readability, supported state version, and directory/file access
458
- and permissions, without initialization, migrations, or permission changes.
459
- - Password-store backend and credential access. On Linux, observations about
460
- `secret-tool`, D-Bus, and the runtime directory help distinguish launch issues.
461
- - Actual node time and account APIs, configured network, and a bounded Commons
462
- account stream. An unopened wallet account can use the configured representative
463
- for an observable snapshot. No snapshot is reported as unverified, not as proof
464
- that an infinite idle stream is broken.
465
- - Fresh worker output validated by Commons against a random public target.
466
- - Initialization, receiving prerequisites, unfinished reset/payments, and MCP
467
- access when diagnosing MCP. Read-only MCP access is a valid choice.
468
- - LIVE USD-price freshness and terms acceptance. USD-only issues are warnings;
469
- ordinary ATTO payments do not require market data or accepted USD terms.
470
-
471
- Each check has a stable `id`, `status` (`pass`, `warn`, `fail`, or `skipped`),
472
- `code`, and message, with safe evidence and remediation steps where useful.
473
- The JSON report contains `context`, `checks`, overall `status`, and `durationMs`.
474
- CLI output is readable text by default; `--json` wraps the full report in
475
- `{"result": ...}` even when checks fail. Exit status is `1` if any check fails,
476
- otherwise `0`. Missing prerequisites produce explicit skipped checks.
477
-
478
- Node reads and streaming each have a 10-second budget; credential and work probes
479
- have a 30-second budget, within the 60-second overall deadline. Ctrl+C cancels
480
- outstanding checks, including native credential probes and their subprocesses.
481
- Doctor does not check npm for updates.
482
-
483
- An agent should call the MCP **`doctor` tool** to inspect the server's own process.
484
- `wallet_status.initialized` describes the saved public wallet identity; status
485
- does not read the password store. If a signing operation returns
486
- `WALLET_CREDENTIAL_MISSING`, the profile remains initialized but its credential
487
- lookup returned empty. Run doctor in that session before attempting recovery;
488
- do not reset or replace the wallet to repair credential access.
489
-
490
- A terminal result cannot establish that an already-running MCP has the same
491
- environment. When a user-owned Linux session socket is available, doctor may test
492
- environment overrides in an isolated credential probe. It returns
493
- `remediation.suggestedEnv` only if the stored credential becomes readable and
494
- matches the wallet. The current check remains failed until the launcher is
495
- corrected. Apply only authorized configuration changes, restart the MCP
496
- connection, and rerun its tool. Doctor never changes environment variables,
497
- client configuration, spending approvals, or terms acceptance; there is no
498
- `--fix` option.
499
-
500
- If MCP cannot start because its profile is invalid, run `atto-mcp doctor` with
501
- that same `--data-dir` in a terminal. Its diagnostic entry point does not need to
502
- open a wallet session. An absent profile uses explicitly labelled defaults and
503
- is not created; an invalid profile is reported without substituting another one.
504
- SQLite may maintain its normal WAL coordination files during inspection; wallet
505
- data, settings, journal entries, approvals, and work caches are unchanged.
506
-
507
- The library exports `runDoctor({ directory?, access?: 'mcp', signal? })` from
508
- `@attocash/cli/core`, independently of `createApplication`. Applications with an
509
- open wallet can also use `call('doctor')`.
172
+ Allow up to 60 seconds. Doctor checks the runtime, profile, password-store
173
+ credential, node, worker, and wallet readiness. It may request password-store
174
+ access and public network data; it does not sign, publish, or repair the wallet.
510
175
 
511
- ## Spending limits and MCP access
176
+ | Symptom | Next step |
177
+ | --- | --- |
178
+ | `atto` is not found | Check `node --version` and `npm --version`; ensure npm's global executable directory is on `PATH`, or use the `npx` form above. |
179
+ | `SECRET_STORE_UNAVAILABLE` | Unlock the OS password store and rerun doctor. On Linux, check `secret-tool` and access to the correct D-Bus session. |
180
+ | `WALLET_CREDENTIAL_MISSING` | Verify the selected profile and credential access. Preserve the profile and pending payments; do not reset it to fix password-store access. |
181
+ | A payment times out or is interrupted | Inspect `atto journal show REQUEST_ID`; retry with the original ID and details. |
182
+ | `SPENDING_LIMIT` or `POOL_BUSY` | Check `atto limits status`, `atto pool status`, and unfinished payments before retrying. |
183
+ | CLI works but MCP fails | Run the MCP `doctor` tool; the server may have a different profile or launch environment. |
512
184
 
513
- CLI spending starts without a cap; **MCP access defaults to read-only**. Set a
514
- per-request cap, multiple rolling day windows, or both. All configured rules must pass.
515
- Changing limits requires a human to review and confirm the change in an
516
- interactive terminal; reading them does not:
185
+ [Full diagnostic behavior and remediation](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#diagnostics).
517
186
 
518
- ```sh
519
- atto limits set --per-payment 10 --daily 25
520
- atto limits set --input '{"perRequest":{"amount":"10","unit":"ATTO"},"rolling":[{"days":1,"amount":"25","unit":"ATTO"},{"days":7,"amount":"100","unit":"ATTO"}]}'
521
- atto limits status
522
- atto limits clear
523
- ```
187
+ ## Spending limits and MCP access
524
188
 
525
- ATTO message signing is a separate profile-specific capability. It starts with no
526
- approved indexes. Grant only the wallet indexes that need unattended signatures
527
- from a local terminal; MCP signing also requires the usual `spend` access:
189
+ CLI spending starts **without an amount cap**. Set shared limits in your own
190
+ terminal; changes require interactive review and confirmation:
528
191
 
529
192
  ```sh
530
- atto limits set --message-signing-indexes 0,1
193
+ atto limits set --per-payment 1 --daily 10
531
194
  atto limits status
532
- atto limits set --message-signing-indexes none
533
195
  ```
534
196
 
535
- `atto message sign --index 0 --text 'exact challenge'` signs the exact UTF-8
536
- bytes; use `--hex` for arbitrary bytes, including the empty byte sequence. The
537
- input is capped at 64 KiB, and no trimming or Unicode normalization is applied.
538
- Quote whitespace and line breaks as part of the argument when they are part of
539
- the challenge. Shell command substitution strips trailing newlines, so use
540
- `--hex` when a trailing newline or other exact byte sequence must be preserved.
541
- The result includes the selected index, address, public key, and 128-character
542
- hex signature.
543
- `atto message verify --address <address> --signature <hex> --text 'exact challenge'`
544
- checks a signature without reading wallet credentials. Use `--public-key <hex>`
545
- instead when only the public key is available. Message signatures use the
546
- Commons `ATTO Signed Message v1` framing. Approving an index permits generic
547
- authentication and controller-approval signatures for that key. Grant only
548
- keys approved for those purposes, and sign only challenges you trust.
549
-
550
- Amount flags default to ATTO; use `--unit RAW` for raw amounts. Omitted limits
551
- are preserved, and `--daily` replaces only the rolling 24-hour rule. Advanced
552
- `--input` replaces the entire policy and cannot be combined with amount flags.
553
- Pool configuration also preserves omitted settings; use `--no-consolidate` to
554
- disable consolidation explicitly.
555
-
556
- `limits set` preserves the existing MCP access mode unless you supply
557
- `--access read-only` or `--access spend`. `limits clear` also preserves that mode;
558
- if MCP already has spending access, clearing its limits permits unlimited sends.
559
- It also preserves message-signing grants; revoke those with
560
- `atto limits set --message-signing-indexes none`.
561
- To enable MCP with a bounded policy explicitly:
197
+ This caps each payment at 1 ATTO and total spending at 10 ATTO over a rolling
198
+ 24 hours. Limits aggregate CLI and MCP sends across this profile's accounts;
199
+ uncertain payments keep their allowance reserved. They do not cover payments
200
+ made through other wallet applications.
562
201
 
563
- ```sh
564
- atto --data-dir /absolute/path/to/profile limits set --access spend \
565
- --input '{"perRequest":{"amount":"10","unit":"ATTO"},"rolling":[{"days":1,"amount":"25","unit":"ATTO"}]}'
566
- ```
567
-
568
- MCP `limits_propose` and generic `atto call limits_propose` **only propose** a change.
569
- They cannot apply it. `limits_propose` also accepts `pool` with `indexes` and
570
- `consolidate`, and `messageSigningIndexes`; omitting either preserves its current
571
- setting. `limits_get` returns the active policy, usage, `mcpAccess`, pool,
572
- message-signing indexes, and current proposal.
573
-
574
- The proposal response also includes `approval.changes`: changed `access`, `policy`,
575
- `pool`, and `messageSigningIndexes` settings with `from` and `to` values.
576
- Source-pool approval is separate from spending access and amount limits; adding
577
- another sending account does not necessarily change either. An unlimited policy
578
- means no amount cap.
579
- `approval.commands.atto` and `approval.commands.npx` provide approval alternatives
580
- with the exact profile directory and proposal ID. Preserve their quoting and use
581
- the indicated `approval.shell` (`posix` on Linux/macOS, `powershell` on Windows).
582
- Only the user should run an approval command.
583
-
584
- A human approves or rejects the proposal in their own terminal, using the same
585
- directory as the MCP client's configuration:
202
+ The optional [`@attocash/mcp`](https://www.npmjs.com/package/@attocash/mcp)
203
+ companion starts read-only. Its
204
+ [setup guide](https://github.com/attocash/integrations/blob/main/atto-mcp/README.md#install-and-connect)
205
+ lets you choose a dedicated wallet or share the CLI wallet. Sharing requires the
206
+ **same absolute `--data-dir`** in both interfaces. To allow bounded MCP spending,
207
+ review this in your own terminal with that directory:
586
208
 
587
209
  ```sh
588
- atto --data-dir /absolute/path/to/profile limits approve PROPOSAL_ID
589
- atto --data-dir /absolute/path/to/profile limits reject PROPOSAL_ID
210
+ atto --data-dir /absolute/path/to/profile limits set --access spend --per-payment 1 --daily 10
590
211
  ```
591
212
 
592
- There is no MCP approval tool or noninteractive approval flag. Each proposal is
593
- bound to its profile directory, wallet identity, network, and policy revision.
594
- It expires after 24 hours; a newer proposal replaces the previous ID. Approval
595
- rechecks those details after you confirm.
596
-
597
- Read-only MCP can read data, manage personal labels, watch events, and propose limits. It cannot send,
598
- receive, derive or activate addresses, change representatives or wallet
599
- configuration, or record terms acceptance. Approved spending access enables
600
- these operations, with sends subject to the shared policy. This is an MCP tool
601
- boundary, not a sandbox for programs or shells running as the same OS user.
602
-
603
- Limits accept `ATTO` or `RAW` and aggregate sends through this CLI and MCP across
604
- all derived addresses, including ordinary payments to owned addresses. Internal
605
- transfers in an approved consolidation plan are excluded, so the final payment
606
- counts once. They also exclude
607
- payments made by other wallet applications. Receiving and representative changes do not consume an
608
- allowance. USD sends count their converted RAW amount. Changing limits preserves
609
- historical spending and pending reservations.
610
-
611
- Simultaneous CLI/MCP mutations are coordinated. A send reserves allowance before
612
- signing and records its block hash before publication. If publication is
613
- uncertain, the reservation stays counted. Retry **the same request ID** to check
614
- the existing outcome. A conflicting reuse is rejected; a timeout does not create
615
- a second payment. `wallet status` lists pending sends, and `limits status`
616
- reconciles them against the configured node.
213
+ MCP may propose changes; only local terminal approval applies them. `limits set`
214
+ preserves the existing access mode unless you change it. `limits clear` preserves
215
+ access too, so clearing caps on a wallet with MCP spending enabled allows
216
+ unlimited sends. Message signing requires separate approved indexes. These
217
+ controls govern this wallet's tools; programs running as the same OS user can
218
+ access the OS password store subject to its permissions.
617
219
 
618
- ## Address labels and personal-name payments
220
+ [Policies, proposals, account pools, and signing grants](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#spending-limits-and-mcp-access).
619
221
 
620
- Save names for existing wallet indexes or external addresses without importing
621
- or activating an account:
222
+ ## Address labels and personal-name payments
622
223
 
623
- ```sh
624
- atto labels set 1 "Savings"
625
- atto labels set <atto-address> "Family"
626
- atto labels show 1
627
- atto labels list
628
- atto labels list --all --search treasury
629
- atto labels list --all --refresh
630
- atto labels remove 1
631
- atto send --to-label "Family" --amount 1 --request-id family-payment-1
632
- ```
224
+ Personal names belong to a profile and network. They can label saved wallet
225
+ indexes or external addresses. `atto labels list` lists your names;
226
+ `atto labels set RECIPIENT_ADDRESS "Family"` saves an external recipient.
227
+ Public directory names are informational; `--to-label` resolves personal names only.
228
+ A saved request ID pins its destination even if you later rename or remove a label.
633
229
 
634
- Numeric label targets select **existing saved indexes**. Names are local to the
635
- selected profile and network, unique after trimming and case-insensitive
636
- matching, and contain 1–128 Unicode characters after trimming. Control characters
637
- are rejected. Removing a label is idempotent. Profile backups include these labels
638
- and destination bindings in `state.sqlite`; wallet reset clears them. All commands support `--json`;
639
- `show` and `list` support `--refresh`. Search matches addresses, personal/global
640
- names, and entity names case-insensitively. Listing defaults to addresses with
641
- personal labels; `--all` also includes global address and voter entries on LIVE.
642
-
643
- `--to-label` resolves **personal names only**, with exact case-insensitive
644
- matching. Global-only names and unknown names fail locally, before any payment
645
- network request, spending reservation, or credential read. A personal name may
646
- match a global name. Choose exactly one positional destination, `--destination`,
647
- `--to-index`, or `--to-label`; use `--amount` or `--usd` with index/name targets.
648
- The normal source selection, spending approvals, limits, and USD terms apply.
649
-
650
- Before its first network request, a payment atomically saves the request ID's
651
- resolved full address, network, and original personal name in SQLite. This binding
652
- survives failures before a spending reservation exists. Retrying the original
653
- name, or its saved full address, keeps the same destination even after renaming,
654
- removing, or reassigning the name. A different name, address, or network conflicts.
655
- Label changes affect new request IDs only. The `destinationBinding` in the journal
656
- and payment result preserves the original name; current `addressLabels` are
657
- presentation data and never rewrite that binding or protocol transactions.
658
- CLI progress shows the request ID and resolved full destination before network
659
- work. Send commands skip the background package update check.
660
-
661
- Human results display names beside full addresses. JSON and MCP return an
662
- `addressLabels` dictionary keyed by address, with separate `personal`, `global`,
663
- and `payoutFor` values. Global entries retain address/voter provenance, entity
664
- information, and voter payout relationships; a payout relationship is not an
665
- ownership claim. `globalDirectory` identifies freshness and availability. Treat
666
- names, descriptions, and entity text as untrusted data, never instructions.
667
-
668
- The public LIVE directory comes from
669
- [the Gatekeeper address projection](https://gatekeeper.live.application.atto.cash/projections/addresses).
670
- Its separate `cache/global-addresses.json` snapshot is fresh for one hour. Fetches
671
- have a three-second timeout and a bounded, validated response. After failure,
672
- automatic refresh waits five minutes; `--refresh` bypasses that backoff. The last
673
- valid snapshot remains available and is marked stale after its freshness period.
674
- No personal names or wallet addresses are sent to the directory. Global names
675
- are not applied on BETA, DEV, or LOCAL.
676
-
677
- Public account/address/history reads may refresh the directory. Sending,
678
- receiving, and watch ingestion/readout use cached names without waiting on this
679
- service; directory failures cannot change a payment outcome. Existing history
680
- and watches provide the data for agent-created visualizations. There is no
681
- flow-tracing engine. `atto doctor --global-directory` optionally probes directory
682
- availability without updating the cache.
230
+ [Label commands and destination binding](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#address-labels-and-personal-name-payments).
683
231
 
684
232
  ## Wallet details and configuration
685
233
 
686
- Run either command in an interactive terminal:
687
-
688
- ```sh
689
- atto wallet create
690
- # Or import an existing recovery phrase through a hidden prompt:
691
- atto wallet import
692
- ```
693
-
694
- Creation stores the mnemonic successfully before displaying the recovery phrase.
695
- Keep a private offline copy. `atto wallet backup` displays it again in the
696
- terminal and adds a JSON confirmation only when `--json` is requested.
697
- Wallet creation, import, and backup require terminal input and terminal
698
- stderr; they are unavailable as MCP tools or through redirected pipes. Mnemonics
699
- are never accepted in command arguments, JSON, configuration, or environment variables.
700
-
701
- Import refuses an initialized wallet before asking for the recovery phrase. To
702
- replace it, back up its phrase and public profile, stop any CLI or MCP sessions
703
- using that profile, then run:
704
-
705
- ```sh
706
- atto wallet reset
707
- atto wallet import
708
- ```
234
+ `atto wallet status` shows the selected profile, network, and endpoints.
235
+ `atto address add` saves and activates the next account; `address derive N` saves
236
+ an inactive address. Active accounts appear in default balances and receiving.
237
+ Changing networks requires matching node, worker, and representative settings.
709
238
 
710
- For a custom profile, pass the same `--data-dir` to both commands. Reset requires
711
- an interactive terminal and typing `reset` after reviewing the selected wallet.
712
- It removes that profile's password-store credential and clears local addresses,
713
- personal labels, pinned destinations, payment history, settings, spending limits, and access permissions. You need the saved
714
- recovery phrase and account indexes to access its funds again. Profile metadata
715
- and database lock files stay in place so the credential namespace and coordination
716
- remain stable.
717
- Other open sessions and unresolved payments prevent reset. If reset is interrupted,
718
- run it again to finish before creating or importing a wallet. After upgrading from
719
- a version without reset support, restart existing CLI/MCP processes before using
720
- this command.
721
-
722
- New standard CLI profiles use the **Atto CLI** password-store service. Existing
723
- legacy and custom profiles retain **Atto MCP** and their existing credential
724
- accounts; no keys are moved. Neither service reads or overwrites the desktop
725
- Atto wallet. See [profiles and recovery](#profiles-and-recovery) for directories
726
- and compatibility. Index `0` starts active. Deriving another
727
- index saves its public address; activating it includes it in default balance
728
- queries and automatic receiving. The network account opens on its first receive.
729
- At most 100 addresses can be active at once; deactivate one before activating
730
- another when that limit is reached.
239
+ See [wallet configuration](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#wallet-details-and-configuration)
240
+ for account management, endpoints, and reset behavior.
731
241
 
732
- ```sh
733
- atto wallet status
734
- atto address add
735
- atto address list
736
- atto balances
737
- atto balances --all
738
- ```
739
-
740
- `address add` saves and activates the next index after the highest saved index.
741
- Use `address derive N` to save a specific inactive address, or `address activate N`
742
- to derive and activate one. Balances include active accounts by default;
743
- `--all` includes every saved address and `--index N` selects one. Saved accounts
744
- show their index and activation state alongside their balance.
745
-
746
- Defaults use the Atto wallet's LIVE endpoints and twelve-representative pool.
747
- Automatic receiving is enabled with a minimum of `1 RAW`. It runs while
748
- `atto wallet receive` is running. MCP also runs it when that profile
749
- has locally approved spending access; read-only MCP does not receive funds or
750
- make other wallet changes. Finite CLI commands do their requested operation and
751
- exit. Stop a persistent command with Ctrl+C.
752
-
753
- `wallet receive` reports pending payments, processing, confirmed receives, and
754
- retries as they happen, including the account index, amount, and transaction hashes.
755
- Connection errors are shown with their retry delay. `--json` emits the initial
756
- wallet status followed by one `result` object per progress event; its `event`
757
- field is `pending`, `receiving`, `received`, `retry`, `skipped`, or `reconnecting`.
758
- Subscriptions use Commons' streaming APIs. The CLI does not impose a deadline
759
- for the first payment or response headers. Finite list commands still stop at
760
- their requested collection deadline.
761
-
762
- ```sh
763
- atto wallet receive
764
- atto wallet configure --no-auto-receive
765
- atto wallet configure --auto-receive
766
- atto wallet configure --representative <atto-address>
767
- ```
768
-
769
- Configuration updates preserve omitted settings. Supply at least one option.
770
- `--representative` changes the default used to open accounts; use
771
- `atto representative change <address>` to change an existing account's representative.
772
- Selecting the account's current representative returns `REPRESENTATIVE_UNCHANGED`
773
- without signing or publishing a transaction.
774
- `wallet status` shows the profile directory and whether receiving runs in that
775
- process; it does not report receiving sessions in other terminals.
776
-
777
- To use another network, configure its node, work server, and representative
778
- explicitly. A network name alone does not replace the other settings:
242
+ ### Fund a Marketplace account
779
243
 
780
- ```sh
781
- atto wallet configure --network LOCAL \
782
- --node-url http://127.0.0.1:8080 --worker-url http://127.0.0.1:8081 \
783
- --representative <atto-address>
784
- ```
244
+ Connect the wallet locally, then fund the configured Marketplace account using
245
+ shared spending limits and a durable request ID. See
246
+ [Marketplace connection and top-ups](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#fund-a-marketplace-account).
785
247
 
786
- Endpoint URLs accept HTTP(S) without embedded credentials, query strings, or
787
- fragments. Pending uncertain sends must be resolved before changing the network
788
- or node endpoint.
248
+ ### Review a Marketplace wallet approval
789
249
 
790
- Settings are saved in `state.sqlite` inside the selected profile directory
791
- (normally `~/.local/share/atto-cli` on Linux), in the `settings` table's
792
- `settings` row. Its JSON contains `nodeUrl`, `workerUrl`, and the other wallet
793
- settings. Use `atto wallet status` to view them and `atto wallet configure`
794
- to change them.
250
+ Review Marketplace's exact request file and typed challenge in your own terminal.
251
+ See [local proof approvals](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#review-a-marketplace-wallet-approval)
252
+ for origin checks, file requirements, and native Windows limitations.
795
253
 
796
254
  ## Profiles and recovery
797
255
 
798
- MCP setup defaults to a dedicated wallet; choose the existing CLI wallet option
799
- to share one. Run `npx --yes @attocash/mcp@latest setup`, or follow the
800
- [MCP setup guide](https://github.com/attocash/integrations/tree/main/atto-mcp#install-and-connect).
801
- The generated client configuration saves your selection as an explicit
802
- `--data-dir`, independently of package installation or npm cache locations.
803
-
804
- Preserve the state directory when restoring or moving an installation: it holds
805
- spending history, request IDs, payment metadata and consolidation progress, pending
806
- publication records, personal labels for every network, pinned payment destinations,
807
- and public address metadata. Recreating a mnemonic alone
808
- does not restore those records.
809
- Stop wallet processes before backing up or moving state. New CLI installations
810
- use the standard CLI directory below. If the legacy directory already contains
811
- `state.sqlite`, CLI commands without `--data-dir` continue to use that legacy
812
- wallet:
813
-
814
- | OS | Standard CLI directory | Legacy directory |
815
- | --- | --- | --- |
816
- | Linux | `$XDG_DATA_HOME/atto-cli`, or `~/.local/share/atto-cli` | `$XDG_DATA_HOME/atto-mcp`, or `~/.local/share/atto-mcp` |
817
- | macOS | `~/Library/Application Support/Atto CLI` | `~/Library/Application Support/Atto MCP` |
818
- | Windows | `%LOCALAPPDATA%/Atto CLI` | `%LOCALAPPDATA%/Atto MCP` |
819
-
820
- Windows falls back to `~/AppData/Local` when `LOCALAPPDATA` is unset. The dedicated
821
- MCP directory is `profiles/mcp` inside the legacy directory. MCP without an
822
- explicit `--data-dir` selects that dedicated profile, not the CLI default.
823
- Existing MCP clients that previously omitted the option should choose their
824
- existing wallet during setup or specify its old directory explicitly.
825
-
826
- Both executables accept `--data-dir <directory>`. The legacy default keeps its
827
- `default` credential account; other accounts are derived from the absolute path.
828
- New standard CLI profiles also contain public `profile.json` metadata selecting
829
- the **Atto CLI** service. **Include this file in profile backups.** The marker
830
- also pins a newly selected standard CLI default, so legacy state created later
831
- does not silently switch wallets; creating an explicit standard profile alongside
832
- an existing legacy wallet preserves the legacy default. An older wallet already
833
- at that path without the marker retains **Atto MCP**. Custom and
834
- dedicated MCP profiles retain **Atto MCP** as well. Selecting the same absolute
835
- directory from either interface selects the same credential and spending state.
836
- Using the same recovery phrase in separate profile directories does not share
837
- locks, limits, journals, or request IDs. Those profiles still control the same
838
- on-chain accounts, so concurrent mutations can compete for an account head.
839
- Use one shared profile to coordinate CLI and MCP operations on the same wallet.
840
-
841
- Keep the same absolute directory when restoring whenever possible. A different
842
- path selects its own credential account and may select a different service;
843
- recovery there requires restoring the corresponding password-store entry before
844
- resuming payments. Preserve the original state and service metadata. No mnemonic
845
- is stored in the profile directory.
846
-
847
- If the password store is locked or unavailable, unlock it and retry. If the
848
- mnemonic is lost from the password store, recover it from your private backup
849
- using `atto wallet import` in an uninitialized profile. Preserve the old public
850
- state and pending-send records for reconciliation before resuming payments.
256
+ The recovery phrase stays in the OS password store. The profile directory holds
257
+ public state, settings, personal names, payment journals, request IDs, and pending
258
+ payment records. **Back up both your recovery phrase and the complete profile.**
259
+ Stop wallet processes before copying the profile; include `profile.json` when present.
260
+
261
+ Use `atto wallet status` to find the actual directory. Fresh CLI installations use
262
+ `~/.local/share/atto-cli` on Linux (or `$XDG_DATA_HOME/atto-cli`),
263
+ `~/Library/Application Support/Atto CLI` on macOS, and `%LOCALAPPDATA%/Atto CLI`
264
+ on Windows. Existing installations may retain a legacy directory.
265
+
266
+ Keep the same absolute path when restoring where possible: the path selects the
267
+ credential account. Importing the same phrase into separate profiles does not
268
+ share locks, spending limits, or request IDs, and concurrent payments may conflict.
269
+ A recovery phrase alone does not restore the journal or pending payment records.
270
+ Preserve those records and follow the
271
+ [recovery and profile reference](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#profiles-and-recovery)
272
+ before resuming payments. `wallet reset` deletes local wallet state and its stored
273
+ phrase; it is not a password-store repair command.
851
274
 
852
275
  ## Background receiving and work preparation
853
276
 
854
- `atto wallet receive` keeps automatic receiving in the current terminal. To
855
- keep receiving after the terminal exits, use:
856
-
857
277
  ```sh
858
278
  atto wallet receive --background
859
279
  atto wallet receive status
860
280
  atto wallet receive stop
861
281
  ```
862
282
 
863
- The background receiver uses the same profile selected by `--data-dir`, the OS
864
- password store, active addresses, minimum receive amount, and automatic
865
- receiving setting. It does not install a service, does not start after reboot,
866
- and does not grant MCP spending access. `wallet status` reports its separate
867
- state and latest operational error. Stop it before resetting a profile.
868
-
869
- All three commands accept `--data-dir <directory>` and `--json`. Starting or
870
- stopping repeatedly is safe. Start acknowledges local initialization; it does
871
- not promise that the node or password store is reachable. The detached process
872
- inherits your login environment and needs access to the OS password store. On
873
- Linux, keep the Secret Service session available; on macOS and Windows, allow
874
- the CLI to access its credential. Check `wallet receive status` for retry errors.
875
- No recovery phrase is stored in the public profile or passed on the command line.
876
-
877
- Stop prevents new receives and reports `stopping` until the current operation
878
- finishes. A crashed receiver reports `stopped`; start it explicitly again after
879
- a crash, reboot, or restoring a backup. Foreground and MCP receivers may coexist,
880
- but stopping this background receiver does not stop those separate sessions.
881
-
882
- After a completed send, receive, representative change, or approved pool step,
883
- the CLI may finish public proof-of-work preparation in a short detached process.
884
- This contains only public account heads and worker settings, runs for at most a
885
- minute, and caches usable work for a later transaction. A changed account head
886
- or an immediate transaction can still require fresh work.
887
- The worker exits when its queue is drained, keeps at most two speculative
888
- requests active, and leaves failed or unfinished jobs eligible for a later CLI
889
- invocation. Reset cancels queued preparation before clearing the profile.
283
+ The detached receiver uses the same profile and password store. It does not
284
+ restart after reboot; inspect its status for credential or connection errors.
285
+ After account changes, a short detached worker may prepare public proof-of-work
286
+ for later payments. See [background behavior](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#background-receiving-and-work-preparation).
890
287
 
891
288
  ## Update notices
892
289
 
893
- Interactive CLI commands can show a notice on stderr when a newer stable CLI
894
- version is available. The notice includes the exact installation command;
895
- updates are always manual. Version checks run in the background, with each
896
- attempt cached for 24 hours, including failed attempts. Their results appear
897
- on a later command. Network and cache failures are silent.
898
-
899
- Use `--no-update-notifier` or set `NO_UPDATE_NOTIFIER` to disable notices and
900
- checks. They are also disabled with `--json`, redirected stdout or stderr,
901
- CI, or `NODE_ENV=test`. MCP and the `@attocash/cli/core` library do not check
902
- for updates or display notices.
903
-
904
- Checks request public package metadata from the npm registry and send no wallet
905
- data. The cache contains only public version information and timestamps,
906
- separately from wallet state:
907
-
908
- | OS | Update cache |
909
- | --- | --- |
910
- | Linux | `$XDG_CACHE_HOME/atto-cli/update.json`, or `~/.cache/atto-cli/update.json` |
911
- | macOS | `~/Library/Caches/atto-cli/update.json` |
912
- | Windows | `%LOCALAPPDATA%/atto-cli/Cache/update.json`, or `~/AppData/Local/atto-cli/Cache/update.json` |
913
-
914
- Replace `VERSION` below with the version shown in the update notice to
915
- update a global CLI installation:
916
-
917
- ```sh
918
- npm install --global @attocash/cli@VERSION
919
- ```
920
-
921
- If MCP is installed too, update the matching pair and restart the MCP process:
922
-
923
- ```sh
924
- npm install --global @attocash/cli@VERSION @attocash/mcp@VERSION
925
- ```
926
-
927
- To use the wallet engine in another application, see the [library API guide](https://github.com/attocash/integrations/blob/main/docs/library-api.md).
290
+ Update a global installation with `npm install --global @attocash/cli@latest`.
291
+ If you also use MCP, update the matching CLI/MCP pair and restart the MCP server.
292
+ Interactive commands may show a newer-version notice on stderr; updates are
293
+ manual. Use `--no-update-notifier` or `NO_UPDATE_NOTIFIER` to disable checks.
294
+ Checks are also disabled for JSON output, redirected output, and CI.
295
+ [Update behavior and cache locations](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#update-notices).
928
296
 
929
297
  ## Install from source
930
298
 
931
- Clone the repository and build the local packages:
932
-
933
- ```sh
934
- git clone https://github.com/attocash/integrations.git
935
- cd integrations
936
- npm ci
937
- npm run pack
938
- npm install --global ./attocash-cli-0.0.0.tgz
939
- ```
940
-
941
- To test MCP with the same local CLI build, install both artifacts together:
942
-
943
- ```sh
944
- npm install --global ./attocash-cli-0.0.0.tgz ./attocash-mcp-0.0.0.tgz
945
- ```
946
-
947
- For development and testing, see the [contributor guide](https://github.com/attocash/integrations/blob/main/docs/contributing.md).
299
+ See the [source build instructions](https://github.com/attocash/integrations/blob/main/docs/cli-reference.md#install-from-source)
300
+ and [contributor guide](https://github.com/attocash/integrations/blob/main/docs/contributing.md).
301
+ For help or bugs, [open a GitHub issue](https://github.com/attocash/integrations/issues)
302
+ with your CLI version and sanitized diagnostics. Never include recovery words.
303
+ Licensed under [BSD-3-Clause](https://github.com/attocash/integrations/blob/main/atto-cli/LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@attocash/cli",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Atto wallet CLI and reusable wallet engine with local key custody and shared spending limits",
5
5
  "license": "BSD-3-Clause",
6
6
  "type": "module",