@capxul/cli 4.20.0-beta.26 → 4.20.0-beta.28

package/README.md

@@ -184,19 +184,23 @@ An agent gives the person the link and runs `next.argv`. `payment wait
 APPROVAL_ID` follows the approval: once it is approved it sends it (unless the
 page already did; only one send can claim it) and waits for the payment to
 settle. Its result is the SDK's `{ approval, payments }`. An Organization
-payment's wait carries `--org`.
+payment's wait carries `--org`. Without `--timeout-seconds`, `payment wait` follows
+until the approval lapses and the payment settles, as `send` does; with it, the wait
+stops after that many seconds (1 to 3600) with exit 5 and the same command to run again.
 
 ## Personal Payments
 
 ```sh
-capxul payment retry PAYMENT_ID --confirm --json
+capxul payment retry PAYMENT_ID --json
 capxul payment list --json
 capxul payment get PAYMENT_ID --json
+capxul payment wait PAYMENT_ID --json
 capxul payment wait PAYMENT_ID --timeout-seconds 120 --json
 ```
 
 These commands use the current authenticated session. Add `--email EMAIL` to
 select a saved session. In a terminal, omit the required Payment ID to enter it.
+`wait` follows a Payment until it ends unless `--timeout-seconds` bounds it.
 `get` refuses when the Payment is absent or unavailable to the session. Human
 output shows the full ID, status, amount, counterparty and available receipt.
 
@@ -205,9 +209,11 @@ action. A failed Payment can be a completed observation. The timeout accepts
 1–3600 seconds and includes session restoration. A timeout or unavailable read
 prints exact get/wait commands. Waiting never resubmits a Payment.
 
-Retry returns `{ payments }` and addresses the existing Payment command. It
-never creates a replacement send. It still signs in the terminal through the
-local wallet page until the approval page covers retries.
+Retry prepares the retry of the exact Payment and hands over to the approval
+page, exactly as `payment send` does: the page is the one and only
+confirmation, and `--json` returns `awaiting_approval`, the link and
+`next.argv` for `payment wait <approval id>`. It addresses the existing Payment
+command and never creates a replacement send.
 
 ## Activity
 
@@ -240,7 +246,7 @@ capxul request get REQUEST_ID
 capxul request cancel REQUEST_ID --confirm
 capxul inbox list
 capxul inbox get REQUEST_ID
-capxul inbox pay REQUEST_ID --confirm
+capxul inbox pay REQUEST_ID
 capxul inbox decline REQUEST_ID --confirm
 capxul request list --org ORGANIZATION_ID
 capxul request issue --org ORGANIZATION_ID --input invoice.json --confirm
@@ -248,7 +254,7 @@ capxul request get --org ORGANIZATION_ID REQUEST_ID
 capxul request cancel --org ORGANIZATION_ID REQUEST_ID --confirm
 capxul inbox list --org ORGANIZATION_ID
 capxul inbox get --org ORGANIZATION_ID REQUEST_ID
-capxul inbox pay --org ORGANIZATION_ID REQUEST_ID --permission-id PERMISSION_ID --confirm
+capxul inbox pay --org ORGANIZATION_ID REQUEST_ID --permission-id PERMISSION_ID
 capxul inbox decline --org ORGANIZATION_ID REQUEST_ID --confirm
 ```
 
@@ -295,7 +301,9 @@ Issue accepts a basic payment request or an Invoice request JSON object from
 `--input FILE` or `--input -`. Both require `payer` and an exact positive
 `amount`. A basic request requires an explicit `reference` and accepts an
 optional private `memo`. An Invoice request also supplies `invoice`.
-Issue saves available document PDFs in the common directory by default.
+Issue saves no file. Its human output names the `document render` command for
+each document, and its JSON result is `{ scope, direction, item }`: the issued
+request with its document references, with no document output.
 Human and JSON output include `checkoutUrl` for an Invoice or Memo request
 instruction with a link token. Invoice requests keep `/checkout/invoices/`.
 Basic requests use `/checkout/requests/`. Movement documents do not create
@@ -305,9 +313,8 @@ For a custom deployment, set `CAPXUL_CHECKOUT_FRONTEND_ORIGIN` in both the CLI
 and backend environments. Use the same frontend origin for both.
 Offer create, get, list, revise, and deactivate output also include `checkoutUrl`.
 The checkout page reads current terms and status when the link opens.
-Use `--output-dir DIRECTORY` to change that location. A PDF failure retains the
-issued request and its document references. Do not issue it again to retry PDF
-output; use the printed document render command.
+Save a PDF with the printed `document render` command. Do not issue the request
+again to get a PDF.
 
 ```json
 {
@@ -359,7 +366,6 @@ CLI signer and the SDK fulfillment API. Organization payment requires the
 selected Permission; the backend checks Budget and spending authority. The
 command publishes prepared Payment IDs before signing. A submitted Payment
 is not a settled Payment. Use the printed get/wait commands to inspect its state.
-Returned documents use the same default PDF directory.
 
 A lost reply or timeout gives exact readback in the same session and scope.
 Pay refuses an already prepared Invoice unless you explicitly use `--resume`
@@ -391,12 +397,14 @@ file metadata. Each render uses a new private directory and preserves earlier
 files. `export` writes the original bytes to a new file.
 It refuses an existing output file.
 
-Reads never write files. Payment `get`, `wait` and `list`, Activity detail and
-Payroll `get` and `wait` name each document with the `document render` command
-that saves it. Payment `send` and `retry`, Payroll `run` and Inbox `pay` still
-save available documents as PDFs in the same directory and report them in their
-result. Pending or unavailable documents retain that state. A document failure
-does not change the Payment result or start another Payment.
+Only `document render` and `document export` write files. Reads name each
+document with the `document render` command that saves it: Payment `get`, `wait`
+and `list`, Activity detail, Payroll `get` and `wait`. Writes save nothing either.
+Payment `send` and `retry`, Payroll `run` and Inbox `pay` end with
+`Save the receipt: capxul document render …` once the receipt exists, and
+`request issue` prints that command for each document it issued. No write
+result carries document output. A document that is still pending is named by
+`payment get`.
 
 ## Contact commands
 
@@ -521,25 +529,14 @@ instructions with both Organization and Payment IDs.
 ## Organization Payment retry
 
 ```sh
-capxul payment retry P --org O --confirm --json
-capxul payment retry
+capxul payment retry P --org O --json
 ```
 
 Retry addresses the original command and every Payment in that command. It
-creates no replacement send or request key. A terminal can collect the Payment
-ID. JSON and scripted runs require the Payment ID, the Organization, and
-`--confirm`.
-
-Before signing, the preview shows every original Payment, recipient, exact
-asset and quantity, timing, and state. It also shows the original command and
-stored Budget. A human terminal asks one default-no question, including when
-`--confirm` is supplied. The signer starts after this step. A changed prepared cohort
-or actor refuses before signature.
-
-The result is `{ payments }` in the SDK's original order. Submitted Payments
-can still be pending. A failure, timeout, or interruption retains the selected
-Organization, Payment, and verified sibling IDs with same-scope get/wait
-commands. Retry does not claim settlement from a submission hash.
+creates no replacement send or request key. The Organization's retry is
+prepared for your own key and handed over to the approval page; the page
+shows the whole cohort. `--json` returns the link and `next.argv` for
+`payment wait <approval id> --org O`, which follows every Payment to its end.
 
 ## Permissions
 
@@ -569,11 +566,16 @@ Every Budget write supplies the complete policy:
   "scope": {
     "recipients": { "type": "allowlist", "accounts": ["account_alice"] },
     "actions": ["pay"]
-  }
+  },
+  "refill": "monthly"
 }
 ```
 
 Use an exact admitted AssetId for `A`. The cap must be positive and finite.
+`refill` is `monthly`, which refills the cap every 30 days (a fixed period from
+the block that sets it, not a calendar month), or `none`. A create without
+`refill` means `none`. A change without `refill` keeps the Budget's current
+refill; write `"refill": "none"` to turn a refill off.
 Recipients are `anyone` or 1 to 32 unique Account IDs. Actions are `pay`,
 `commitments`, or both. `pay` covers single and batch Payments. Missing scope,
 duplicate recipients/actions, unknown fields, and an asset mismatch refuse.
@@ -589,7 +591,14 @@ and printed before the first write. Scripted runs require `--request-key` and
 `--confirm`.
 
 Success means submitted and pending application. It does not prove active
-rights. After an interruption or uncertain result, retain the original input,
+rights. Add `--wait` to `create`, `change`, `assign`, `revoke` or `replace` to
+follow the submitted command to its end, as `org permission command wait` does:
+it stops when the command is applied, failed or needs action. The result then
+also holds `command`, the command's view (`status` is `applied`, `failed` or
+`actionable`), and exits 0 in each case, as `command wait` does; read `status`.
+`--timeout-seconds` bounds the signing and, separately, the wait. A wait that
+runs out of time fails with exit 5 and prints the exact `command get` and
+`command wait` lines. After an interruption or uncertain result, retain the original input,
 Organization ID, key, command ID, and execution ID. The key alone cannot restore
 wizard/stdin input.
 
@@ -612,8 +621,8 @@ capxul org payroll groups save --org O --input group.json --confirm [--json]
 capxul org payroll groups remove G --org O --confirm [--json]
 capxul org payroll terms --org O [--json]
 capxul org payroll list --org O [--json]
-capxul org payroll run --org O --input run.json --request-key K --confirm [--json]
-capxul org payroll run --org O --resume K --confirm [--json]
+capxul org payroll run --org O --input run.json --request-key K [--json]
+capxul org payroll run --org O --resume K [--json]
 capxul org payroll get --org O R [--json]
 capxul org payroll wait --org O R --timeout-seconds 120 [--json]
 ```
@@ -640,16 +649,18 @@ refuse before client work.
 In a human terminal, `capxul org payroll run` guides the current Organization,
 Budget, settlement asset, date, roster or known Parties, and actual payout
 quantities. Roster amounts and terms are reference data. The complete preview
-shows each recipient and Safe, quantity, raw units, and adjustment. One
-default-no approval precedes signing, including when `--confirm` is supplied.
-Machine runs require exact scope, input, key, and `--confirm`.
+shows each recipient and Safe, quantity, raw units, and adjustment. The run
+is then prepared and handed over to the approval page, the one and only
+confirmation. Machine runs require exact scope, input and key; `--json`
+returns the approval link and `next.argv` for `payment wait <approval id> --org O`.
 
 The command saves the exact input in protected storage under the verified actor,
 Organization, and key before execution. `--resume K` restores that snapshot.
 It requires the same explicit Organization and cannot combine fresh input or
 another key. Payroll accepts email and Party references. Raw external addresses
 are outside the current run contract.
-Success returns `{ run, requestKey }`; submission does not prove settlement.
+`--resume K` prepares the same run again, so it reopens a pending approval
+rather than paying twice.
 
 Get returns the full authorized run detail, command, ordered items, and recorded
 times. Wait observes the exact run without polling or submitting. It keeps
@@ -810,7 +821,14 @@ SDK's own value for the command, with no CLI wrapper. A list is the SDK page,
 `{ items, nextCursor }`; pass `nextCursor` back as `--after` where the command
 takes one. `--fields a,b` keeps only those fields of `data` (`amount.value`
 reaches inside an object; a list keeps `nextCursor` and picks from each item).
-`--fields` without `--json` refuses.
+`--fields` without `--json` refuses, and so does a typo: a name the result lacks that is a
+letter or two off a name it has (exit 2, `field: "fields"`); the message names it, the
+closest real field and the fields in this result. Any other name the result lacks, such as
+an optional `execution` on a Payment that has none, is left out, as `jq` would.
+The four commands that move money (`payment send`, `payment retry`, `inbox pay`,
+`org payroll run`) check the names against the result they declare before they
+run, so a typo never costs an approval: `status`, `approvalId`, `approvalUrl`,
+`paymentIds`, `expiresAt` and `next`.
 
 A failure contains `error`:
 
@@ -832,13 +850,21 @@ not grant authority or bypass current checks. `error.details.recovery` keeps
 its `kind` (`read` or `retry`) next to the same `argv`.
 
 A person sees one red line for what happened and one for what fixes it (on the
-same line when both fit in 80 columns):
+same line when both fit in 80 columns), then a dim last line, `ref <id>`, for
+support:
 
 ```text
 ✗ Unknown command "paymnt". Did you mean: capxul payment list
 ✗ Not signed in. Try: capxul auth login
+ref 6a0e10d1-06fb-4eed-9c2a-1f6f0c2b7d11
 ```
 
+The `ref` is the backend's request ID when the error carries one, else its
+correlation ID, else this run's `invocationId`. A mistyped command has none,
+because no command started. An error that already quotes its request ID in its
+sentence (a redacted backend error) has no `ref` line. JSON output has no `ref`
+line and is unchanged: read `error.details.requestId` or `invocationId`.
+
 A wallet failure
 also includes its known `error.mode` and allowed `error.details`: wallet stage,
 operation, provider, provider code, and HTTP status. An unknown browser failure
@@ -925,7 +951,7 @@ sign-in; it sets `NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY` and `CAPXUL_SITE_URL` in
 journeys with the built CLI against the local DevNet: sign in, `dev fund`, the home
 screen, a payment (refused with its fix while the wallet setup is unfinished, as
 it is on a DevNet with no wallet provider), requests, offers, Inbox, Organizations,
-the account, `schema`, a typo's fix and `dev key`. The `capxul dev journeys` job in
+the account, `schema`, a typo's fix and `dev key`. The `cli-journeys` job in
 `.github/workflows/devnet-integration.yml` starts the DevNet and runs it.
 
 ## Development commands
@@ -1049,7 +1075,7 @@ a concurrent logout from being undone by a delayed credential save. The backend
 owns expiry and revocation. A failed remote logout is reported as `unconfirmed`;
 local sign-out remains in effect.
 
-`auth profile` returns a backend-read Profile and account lifecycle without opening
+`account show` returns a backend-read Profile and account lifecycle without opening
 the browser. Successful email authentication can return `setupState: "setup-required"`.
 `account retry` returns `setupState: "ready"` only after Core reads a ready Account.
 After logout, profile reads refuse with `NOT_AUTHENTICATED` and exit 3. An invalid
@@ -1064,7 +1090,7 @@ capxul account retry --email you@example.com --wizard
 
 The terminal shows the verified session, Account ID and current lifecycle before
 confirmation. A ready Account starts no wallet work. Missing Account or Profile
-state directs to `account retry`. A deadline stops waiting; check `account status`
+state directs to `account retry`. A deadline stops waiting; check `account show`
 for the same session before retrying.
 
 Read an Organization treasury or deposit target:
@@ -1124,7 +1150,7 @@ capxul offer deactivate OFFER_ID --expected-revision 2 --confirm
 capxul offer list --org ORG_ID
 ```
 
-Use `org offer` and `--org ORG_ID` for each Organization command. Use `--email`
+Add `--org ORG_ID` to run any of these as an Organization. Use `--email`
 to select a saved session. Scripts must supply `--confirm` for each write.
 A terminal shows the proposed change and asks for confirmation. Use `--json`
 for structured output. Lists and reads create no PDF.
@@ -1160,16 +1186,16 @@ reference. Separate purchasers receive separate checkout and settlement IDs.
 ## Request and document flow
 
 Alice issues a basic request or an Invoice to Bob with `request issue`. For an Organization issuer,
-Alice uses `org request issue --org ORGANIZATION_ID`. Issuance saves Alice's PDF
-by default and returns the request ID, document references, and checkout URL.
+Alice uses `request issue --org ORGANIZATION_ID`. Issuance returns the request ID,
+document references, and checkout URL. Alice saves her PDF with the printed
+`document render` command.
 Bob runs `inbox list`, then `inbox get REQUEST_ID`. An Organization
-payer uses the equivalent `org inbox` commands with its explicit Organization.
+payer uses the same `inbox` commands with `--org`.
 
-Bob's Inbox contains the request and document references. It does not receive a
-local PDF automatically. Bob uses the printed `document render` command to save
-his copy. Both participants read the same verified document. Their files can
-have different local paths. `status` shows available request and document counts;
-it does not download documents.
+Bob's Inbox contains the request and document references. Bob uses the printed
+`document render` command to save his copy. Both participants read the same verified document. Their files can
+have different local paths. The home screen (`capxul`) shows how many requests wait
+for you; it does not download documents.
 
 A direct Payment uses the existing Payment and Activity commands. Alice inspects
 her outgoing records. Bob inspects his incoming records after the backend observes
@@ -1183,10 +1209,10 @@ access remains available through the saved document and content hashes. Keep
 those references when retaining a cancelled Invoice.
 
 The shared document directory is `documents` next to the CLI settings directory.
-`CAPXUL_CLI_HOME` selects a separate CLI settings directory. `--output-dir` changes
-the document output location for supported document and payment commands. Each
-render preserves previous files. A failed PDF render does not repeat issuance or
-payment. Retry `document render` with the existing document references.
+`CAPXUL_CLI_HOME` selects a separate CLI settings directory. `document render
+--output-dir` changes the document output location. Each render preserves
+previous files. A failed PDF render does not repeat issuance or payment. Retry
+`document render` with the existing document references.
 
 ## Checkout links
 
@@ -1205,9 +1231,10 @@ External funding requires the correct network, balance, gas, and any exact token
 approval. Payment goes through the Payments contract with the validated snapshot.
 Inspect the resulting state and receipt before reporting payment complete.
 
-CLI `inbox pay` retains its existing CLI signing flow. It does not depend on the
-hosted checkout page. A rejected signature or uncertain reply is not permission
-to send another Payment. Use the printed readback and recovery instructions.
+CLI `inbox pay` prepares the request's Payment and hands over to the approval
+page, as `payment send` does. It does not depend on the hosted checkout page.
+A rejection on the approval page is not permission to send another Payment.
+`--resume` reopens the approval of a request whose Payment is already prepared.
 
 Checkout links do not create recurring billing, automatic debits, booking,
 refunds, or QR codes.