@capxul/cli 4.20.0-beta.1 → 4.20.0-beta.11

package/README.md

@@ -1,7 +1,9 @@
 # Capxul CLI
 
-The CLI provides local diagnostics, an online backend check, and one global
-collection preference. It requires Node 24 or later on macOS or Linux.
+The CLI provides email OTP login, persistent first-party sessions, terminal-owned
+signup, personal and Organization contacts, a bundled Openfort wallet page,
+backend profile and account reads, diagnostics, and one global collection
+preference. It requires Node 24 or later on macOS or Linux.
 
 ```sh
 capxul --help
@@ -14,27 +16,216 @@ capxul telemetry enable --json
 capxul doctor --online --timeout-ms 30000 --json
 ```
 
-Help, version, and completion do not read configuration or contact a server.
+Help and version do not require application credentials or a working backend.
+With no arguments, `capxul` shows the same generated help as `capxul --help`.
+They use the same observation policy as ordinary commands. Shell completion
+machinery and collection controls send no observation records.
 `doctor` checks local configuration unless `--online` is present. An online
 check uses the public Capxul SDK and verifies the backend response nonce.
 It does not authenticate a person or submit a transaction.
 
+## Contact commands
+
+```sh
+capxul contact list [--include-hidden]
+capxul contact get --entry-id PARTY_ID
+capxul contact add --input FILE|- [--confirm]
+capxul contact label --entry-id PARTY_ID --label TEXT [--confirm]
+capxul contact hide --entry-id PARTY_ID [--confirm]
+capxul contact unhide --entry-id PARTY_ID [--confirm]
+
+capxul org contact list --org ORGANIZATION_ID [--include-hidden]
+capxul org contact get --org ORGANIZATION_ID --entry-id PARTY_ID
+capxul org contact add --org ORGANIZATION_ID --input FILE|- [--confirm]
+capxul org contact label --org ORGANIZATION_ID --entry-id PARTY_ID --label TEXT [--confirm]
+capxul org contact hide --org ORGANIZATION_ID --entry-id PARTY_ID [--confirm]
+capxul org contact unhide --org ORGANIZATION_ID --entry-id PARTY_ID [--confirm]
+```
+
+Personal commands use the authenticated Account address book. Organization
+commands require one explicit `--org` or `--org-id`; they never use the saved
+Organization read default. `list` omits hidden entries unless
+`--include-hidden` is present. `get`, `label`, `hide`, and `unhide` address one
+stable Party with `--entry-id`.
+
+`add --input` reads the existing `AddressBookAddInput` JSON shape. For example:
+
+```json
+{
+  "ref": { "kind": "email", "email": "supplier@example.test" },
+  "label": "New Supplier"
+}
+```
+
+Use `--input -` to read the same object from stdin. An interactive `add` can
+collect the reference kind, value, and optional label instead. Interactive
+writes show the actor and exact contact change, then ask a default-no question.
+JSON, CI, and other noninteractive writes require `--confirm` before the CLI
+creates a client. Contact writes do not start a browser signer.
+
+Success data is the SDK value without a CLI wrapper: `list` returns
+`AddressBookEntry[]`, `get` returns `AddressBookEntry | null`, and each mutation
+returns `AddressBookEntry`. Human `get` prints `No contact found` for null and
+exits successfully. Entries retain their stable PartyId, exact reference,
+relationships, hidden state, and last activity time.
+
+## Organization commands
+
+```sh
+capxul org list --json
+capxul org use --org ORGANIZATION_ID
+capxul org status --org ORGANIZATION_ID --json
+capxul org get --json
+capxul org me --json
+capxul org members --json
+capxul org member list --json
+capxul org member get --account-id ACCOUNT_ID --json
+capxul org wait --timeout-seconds 120 --json
+capxul org create --name NAME --handle HANDLE --country CC [--bio TEXT] [--size TEXT] [--confirm]
+capxul org retry --org ORGANIZATION_ID [--confirm]
+```
+
+These commands accept `--email`. Without it, they restore the protected current
+session. Organization reads accept `--org` or its alias `--org-id`. Identical
+repeated IDs are accepted. Different IDs are refused.
+
+A read without --org uses the saved read default, then this machine's
+recovery ID, then the one unfinished setup returned by the backend. org list
+includes unfinished founder setups. This works from a clean authenticated home.
+If more than one Organization is possible, give an exact --org. A ready
+Organization must still appear in current access.
+
+org use saves a protected per-person read default. The default grants no
+authority. Member lookup uses an exact AccountId. Reads do not sign or change
+setup state.
+
+org wait opens one exact setup subscription. It continues when needsAttention
+has a scheduled next check. It stops at ready, failed, awaitingAuthorization,
+or attention without a next check. It does not request a check or poll. The
+timeout accepts 1 to 3600 seconds and defaults to 120. A deadline returns
+CLI_DEADLINE at exit 5; Ctrl-C returns CANCELLED at exit 130.
+
+## Invitation commands
+
+```sh
+capxul org invite list [--mine] [--limit N] [--cursor C] [--phase PHASE ...] [--org O]
+capxul org invite get --invitation-id I [--org O]
+capxul org invite wait --invitation-id I [--org O] [--timeout-seconds N]
+capxul org invite review --invitation-id I --org O [--timeout-seconds N]
+capxul org invite accept --invitation-id I --offer-digest D --org O [--confirm] [--timeout-seconds N]
+capxul org invite decline --invitation-id I --org O [--confirm]
+capxul org invite cancel --invitation-id I --org O [--confirm]
+capxul org invite resend --invitation-id I --org O [--confirm]
+capxul org invite retry --invitation-id I --org O [--confirm]
+capxul org member invite (--to-email E | --account-id ID) [--budget-id B ...] [--permission-id M ...] [--new-budget-name N --asset A (--limit Q | --unlimited) (--recipient-account ID ... | --any-recipient) --actions pay[,commitments]] --org O [--request-key K] [--preview] [--confirm]
+```
+
+`org invite list` returns your own offers. It accepts `--limit` (1--100),
+`--cursor`, and repeated `--phase` values, and its result carries `invitations`,
+`nextCursor`, and `observedAt`: pass `nextCursor` back as `--cursor`, and change
+no other filter between the two calls. `--mine` names the own-offer projection,
+which is already the default. With `--org O` the command returns that
+Organization's invitations for a current Admin instead; the Organization list is
+not filtered to you, so `--mine` together with `--org` refuses with exit 2. The
+other invitation commands require an exact `--invitation-id`.
+
+`org invite get` and `org invite wait` use `--org` when you name it. Without
+`--org` they walk your own-offer pages, 100 rows per request, until they find
+the invitation or the pages end. They never consult the saved read default, and
+an offer you cannot see is refused. `--timeout-seconds` bounds the resolution
+and the read together on both commands.
+
+`org invite wait` only reads. It finishes when the offer settles or when the
+recovery asks a person to act. It never retries, resends, or accepts.
+
+`org invite review` requires `--org`, returns the current `InvitationView`
+directly in `data`, and performs no write or signing.
+
+The four transitions require `--org` in both modes, as `accept` does. They never
+author a new offer. A noninteractive or JSON run requires `--confirm`. An
+interactive run shows the resolved current offer and asks a default-no question.
+
+`org member invite` authorizes one exact offer. `--preview` writes nothing and
+needs neither a request key nor confirmation. A noninteractive write requires
+`--request-key` and `--confirm`. An interactive run prints the request key it
+used before it submits, so a lost response is recoverable with the same
+identity. At most one `--new-budget-name` is accepted per command.
+
+`org invite accept` is the exact grantee's consent commit. It takes the exact
+digest the offer shows as `--offer-digest`: a noninteractive or JSON run must
+supply it, and without it the command refuses with exit 2 before it creates a
+client. An interactive run may omit it, and then reads the offer and fills the
+digest from the value it displayed. A digest you state is never replaced by the
+displayed one. `--expected-offer` remains a compatibility spelling, and both
+spellings must match when supplied together. The command returns the
+`InvitationView` directly in `data`. The grant is executed by the deployment's
+technical executor, so the command needs no browser bridge and works in a
+headless or CI session. A repeat with the stored digest returns the same
+accepted result; a different digest refuses and cannot overwrite consent. The
+returned view is the authorization-time view of the consent commit
+(`pending_grant`); read the settled `active` state with `get` or `wait`.
+
+## Organization writes
+
+org create and org retry use the protected current session unless --email names
+one. A JSON or noninteractive write requires --confirm. A terminal write shows
+the current Organization and recovery information, then asks a default-no
+question. The signer starts after confirmation.
+
+org create validates name, handle, and country before client work. It calls
+onboarding.beginOrganization, saves and prints the exact Organization ID,
+authorizes only an awaitingAuthorization setup, then subscribes to setup
+changes. It reports success only after ready and current access. JSON progress
+uses one line per state:
+
+    { "type": "organization.lifecycle", "organizationId": "O", "status": "processing" }
+
+org retry requires one exact --org. It authorizes only awaitingAuthorization.
+For an accepted setup it asks the backend to check the same operation hash
+through setup.resume, then subscribes. Neither command replaces a submitted
+operation. The local recovery record keeps a safe handle and Organization ID
+for convenience; the backend unfinished list supports recovery without it.
+
+--timeout-seconds sets one 1-to-3600-second deadline for the command. A
+deadline stops local work and returns exit 5. If the last observed setup has
+another automatic check scheduled, the message is "Stopped waiting.
+Organization setup continues in the background." Before acceptance or without
+a scheduled check, the message is "Stopped waiting. Read the Organization
+setup status." The error details include the safe Organization ID when known,
+last observed setup state, setup reason, and bounded provider diagnostics.
+Ctrl-C stops local work at exit 130. Neither stop writes a backend failure.
+
 ## Configuration
 
 | Variable                       | Use                                                                                                          |
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
 | `CAPXUL_CLI_HOME`              | Directory for global CLI settings. Defaults to `$XDG_CONFIG_HOME/capxul/cli`, or `$HOME/.config/capxul/cli`. |
-| `CAPXUL_PUBLISHABLE_KEY`       | Application publishable key, required for an online check.                                                   |
+| `CAPXUL_PUBLISHABLE_KEY`       | Optional developer override for the bundled first-party staging key.                                         |
 | `CAPXUL_BOOTSTRAP_URL`         | Bootstrap origin. Defaults to `https://api.staging.capxul.com`. Convex Cloud origins are rejected.           |
-| `CAPXUL_POSTHOG_HOST`          | PostHog ingestion origin.                                                                                    |
-| `CAPXUL_POSTHOG_PROJECT_TOKEN` | Project ingestion token. Both PostHog variables are required for export.                                     |
+| `CAPXUL_POSTHOG_HOST`          | Optional development override for the built-in public PostHog ingestion origin.                              |
+| `CAPXUL_POSTHOG_PROJECT_TOKEN` | Optional development override for the built-in public project ingestion token.                               |
 | `CAPXUL_TELEMETRY_DISABLED`    | Set to `true` to disable remote observation regardless of the saved preference.                              |
 
-Collection defaults to enabled. Local commands send no remote signals.
+The published CLI includes the verified first-party staging application key and
+Capxul-owned public ingestion configuration. You do not need key or PostHog
+environment variables. A different bootstrap origin requires an explicit key. Collection defaults to enabled for
+ordinary local and online commands, help, version, and safely attributed argument
+refusals. Parser refusals produce a completion without a start. Early native
+global errors with no resolved command route send nothing, because the CLI
+cannot determine whether they belong to a silent collection control.
 `telemetry disable` saves one preference for the OS user and sends no final
 remote event. Already running CLI processes check the current preference before
 each export. Requests already sent cannot be recalled. `telemetry status`
 reports the stored preference, effective policy, configuration, and reason.
+`--log-level` controls normal diagnostic output, not collection. An eligible
+invocation still produces its remote completion unless collection is disabled.
+
+Eligible commands reuse a random anonymous identifier stored in the protected
+CLI directory. Invocation and trace identifiers remain separate. A first-use
+marker records the first eligible observed use, not a download or a verified
+person. If this state cannot be accessed safely, observation stops and the
+command retains its normal result. Delivery is bounded and best-effort; the CLI
+does not keep a persistent activity queue.
 
 Settings use a versioned JSON file in a directory with mode `0700`. The file has
 mode `0600`. Writes are atomic and serialize between processes. A later writer
@@ -43,8 +234,14 @@ unsafe permissions, symlinks, and corrupt state produce a storage failure.
 
 ## Output
 
-`--json` writes one version 1 envelope to stdout. Success contains `data`.
-Failure contains `error.code` and CLI-owned `error.message`. Each envelope has
+`--json` writes one version 1 envelope to stdout. Success contains `data`, which
+can be an object, array, or null according to the command's SDK result.
+Failure contains `error.code` and CLI-owned `error.message`. 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
+uses mode `unknown`. No provider message, token, signature, or native cause enters
+the result. These fields remain available when collection is off or
+`--log-level none` is set. Each envelope has
 `command`, `invocationId`, and `outcome`. An invocation ID is null before a
 command starts. Human errors go to stderr.
 
@@ -93,6 +290,15 @@ compinit
 Use `npm update -g @capxul/cli` or `brew upgrade xelmar-tech/tap/capxul` to update.
 Use one installer for the `capxul` executable to avoid conflicting PATH entries.
 
+After a successful human command, help, or version request, the CLI can show an
+update notice on terminal stderr. It checks the public npm `latest` tag at most
+once per 24 hours. It shows only the command for the verified running npm-global
+or Homebrew installation. It does not execute that command. Unknown installations,
+development versions, JSON output, redirected stderr, CI, shell completion, and
+all `telemetry` commands receive no notice. The optional check has one 500 ms
+budget. Safe failed attempts are cached. Storage or network failures remain
+silent and do not change the command result. This check sends no telemetry.
+
 ## Development commands
 
 ```sh
@@ -105,3 +311,103 @@ vp exec node --test --test-name-pattern='@capxul/cli' scripts/__tests__/pack-ins
 The last command installs the tarball outside the workspace and exercises the
 installed executable with isolated settings and a local HTTP server. The CI
 `CLI / Linux / Node 24.0.0` job runs this proof at the declared minimum version.
+
+## Email login and session restoration
+
+This CLI establishes a first-party BetterAuth session. It has broader authority
+than the earlier native `account:read` grant. Existing native grants remain
+stored and tagged as `legacy-native-grant` in status. A profile read asks for an
+explicit new login; it never exchanges the old grant for a broader session.
+Logout forgets and attempts to revoke both credential types for the selected email.
+
+`capxul auth login` and `capxul auth signup` stay separate commands. On a
+terminal, each command is a wizard. `auth login` asks for the email and a masked
+OTP. It accepts the code as a paste. It retries an invalid code at most three
+times for one request. After sign-in, an incomplete account gets one offer to
+continue setup in the same command. `auth signup` authenticates first, then asks
+for the Profile fields: display name, two-letter country code, and handle. A
+known value is the prompt default, so Enter keeps it.
+
+The browser opens only when the shared Core onboarding journey needs Openfort
+wallet readiness. It shows wallet status only. It has no email, OTP, Profile, or
+approval form.
+
+Ctrl+C or Ctrl+D at a wizard prompt cancels the command. The command prints no
+success result and exits 130. A step that already finished keeps its result: a
+completed sign-in keeps its session.
+
+For an agent, send and verify in separate processes:
+
+```sh
+capxul auth send --email "$TEST_EMAIL" --json
+# Supply the delivered six-digit OTP through stdin, not a command argument.
+capxul auth verify --email "$TEST_EMAIL" --otp-stdin --json
+capxul auth profile --email "$TEST_EMAIL" --json
+# A later process uses the same protected CLI home; no new OTP is required.
+capxul auth profile --email "$TEST_EMAIL" --json
+capxul auth status --email "$TEST_EMAIL" --json
+capxul auth logout --email "$TEST_EMAIL" --json
+```
+
+A machine run never prompts. `auth login` with `--otp-stdin` sends the OTP and
+verifies one code from stdin. It returns the tagged result
+`setupState: "setup-required"` when the account needs setup. It does not start
+setup work, so sign-in never becomes signup.
+
+A fresh machine signup does verification and setup in one command. State every
+Profile field; a missing field refuses with exit 2:
+
+```sh
+# Supply only the delivered OTP through stdin.
+capxul auth signup --email "$TEST_EMAIL" --otp-stdin \
+  --display-name "Test Person" --country GH --handle test_person --json
+```
+
+`--otp-stdin` reads up to 64 bytes, ending at EOF. Pipe from a secret provider or
+use input redirection from a protected file. An invalid value refuses with exit 2. A missing `--otp-stdin` refuses with exit 2 before the command starts client
+work. OTPs are never accepted in argv, persisted in the continuation, or included
+in output.
+
+The local page binds to an OS-selected loopback port. A random launch capability
+is redeemed once and removed from the URL before Openfort starts. The page receives
+only the authenticated wallet token and encryption session in memory. Closing it
+ends the current wallet attempt. Re-run `auth signup` with the same CLI home to
+resume the same Profile and Account without another OTP while the backend session
+remains valid.
+
+`auth signup` returns only two readiness results. `setupState: "ready"` is a
+personal Account that the Account readiness owner reads as ready and deployed,
+and its data carries the public identifiers: the Profile, the public wallet
+address (`smartAccount.signerAddress`), the personal Smart Account address
+(`smartAccount.smartAccountAddress`), the Account ID
+(`lifecycle.accountId`), and the ready status. Any other state returns the typed
+recoverable result `setupState: "setup-required"`, with the lifecycle, its
+failure code, and the command that resumes the journey. A ready Account starts
+no wallet work, so a retry keeps the one Profile, wallet, Smart Account, and
+Account. An interruption keeps the stored session and stores no code, so the
+next command resumes the same setup.
+
+A ready personal Account continues the same journey into Organization creation
+with `capxul org create --name NAME --handle HANDLE --country CC`. The create
+command records the safe recovery handle for that Organization, so an
+interruption or a restart resumes the exact same Organization.
+
+The CLI checks `--display-name`, `--country`, and `--handle` before it opens a
+client, so a malformed value refuses with exit 2 and no code is sent. The handle
+check covers the grammar only: a handle that another person holds, and a reserved
+handle, refuse through the identity owner after sign-in. Both refusals name the
+handle, and neither offers verification-code recovery for a Profile problem.
+
+The version 2 `first-party-session` record stores the opaque provider credential
+in the existing protected plaintext store. Its scope includes the application
+key, issuer, environment, and email. Each process validates restoration with the
+backend; cached session data is not authority. Conditional replacement prevents
+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
+the browser. Successful email authentication can return `setupState: "setup-required"`.
+`auth signup` returns `setupState: "ready"` only after Core reads a ready Account.
+After logout, profile reads refuse with `NOT_AUTHENTICATED` and exit 3. An invalid
+or expired OTP refuses with exit 2.