@capxul/cli 4.20.0-beta.6 → 4.20.0-beta.7

package/README.md

@@ -1,9 +1,9 @@
 # Capxul CLI
 
 The CLI provides email OTP login, persistent first-party sessions, terminal-owned
-signup, 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.
+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
@@ -24,6 +24,51 @@ machinery and collection controls send no observation records.
 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
@@ -60,6 +105,66 @@ No match returns exit 2. Duplicate matches return exit 1.
 seconds and defaults to 120. Timeout returns exit 5; interruption returns 130.
 A successful read can report a failed or pending domain state.
 
+## 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` restore the protected current session and start the
@@ -129,7 +234,7 @@ subscription and the browser bridge.
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
 | `CAPXUL_CLI_HOME`              | Directory for global CLI settings. Defaults to `$XDG_CONFIG_HOME/capxul/cli`, or `$HOME/.config/capxul/cli`. |
 | `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_BOOTSTRAP_URL`         | Bootstrap origin. Defaults to `https://site.preview.abuusama.dev`. Convex Cloud origins are rejected.        |
 | `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.                              |
@@ -162,7 +267,8 @@ unsafe permissions, symlinks, and corrupt state produce a storage failure.
 
 ## Output
 
-`--json` writes one version 1 envelope to stdout. Success contains `data`.
+`--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`. Each envelope has
 `command`, `invocationId`, and `outcome`. An invocation ID is null before a
 command starts. Human errors go to stderr.