@attocash/cli 0.3.1 → 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.
- package/README.md +173 -817
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,947 +1,303 @@
|
|
|
1
1
|
# Atto CLI
|
|
2
2
|
|
|
3
|
-
|
|
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** · [
|
|
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) · [
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
|
|
41
|
+
Run this in your own interactive terminal:
|
|
57
42
|
|
|
58
43
|
```sh
|
|
59
44
|
atto wallet create
|
|
60
45
|
```
|
|
61
46
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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
|
|
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
|
|
75
|
-
running
|
|
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
|
|
82
|
-
|
|
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
|
-
###
|
|
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
|
|
90
|
-
atto labels
|
|
91
|
-
atto
|
|
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
|
-
|
|
95
|
-
|
|
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
|
|
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
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
-
###
|
|
98
|
+
### Check payments and activity
|
|
113
99
|
|
|
114
100
|
| Task | Command |
|
|
115
101
|
| --- | --- |
|
|
116
|
-
| Recent
|
|
117
|
-
|
|
|
118
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
117
|
+
atto journal show invoice-42
|
|
118
|
+
atto send RECIPIENT_ADDRESS 1.25 --request-id invoice-42
|
|
169
119
|
```
|
|
170
120
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
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
|
-
|
|
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
|
|
356
|
-
atto
|
|
357
|
-
atto wallet
|
|
131
|
+
atto --help
|
|
132
|
+
atto send --help
|
|
133
|
+
atto wallet --help
|
|
358
134
|
```
|
|
359
135
|
|
|
360
|
-
|
|
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
|
|
140
|
+
atto --json history --limit 10
|
|
141
|
+
atto --json send RECIPIENT_ADDRESS 1.25 --request-id invoice-42
|
|
403
142
|
```
|
|
404
143
|
|
|
405
|
-
|
|
406
|
-
`{"
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
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
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
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
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
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
|
|
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
|
-
|
|
447
|
-
|
|
448
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
526
|
-
|
|
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 --
|
|
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
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
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
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
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
|
|
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
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
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
|
-
|
|
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
|
-
|
|
621
|
-
or activating an account:
|
|
222
|
+
## Address labels and personal-name payments
|
|
622
223
|
|
|
623
|
-
|
|
624
|
-
atto labels
|
|
625
|
-
atto labels set
|
|
626
|
-
|
|
627
|
-
|
|
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
|
-
|
|
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
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
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
|
-
|
|
711
|
-
|
|
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
|
-
|
|
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
|
-
|
|
781
|
-
|
|
782
|
-
|
|
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
|
-
|
|
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
|
-
|
|
791
|
-
|
|
792
|
-
|
|
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
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
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
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
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
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
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
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
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).
|