primcli 3.0.0-preview.1 → 3.0.0-preview.11

package/README.md

@@ -71,8 +71,9 @@ primitive listen --subscription local-webhook --forward-to http://localhost:3000
 ```
 
 This mode forwards the exact signed body and existing webhook headers. Configure
-the handler with your existing account webhook secret and normal signature
-verification. The CLI never forwards your API credentials. It does not follow
+the handler with the secret the webhook signs with (the account webhook secret,
+or the webhook's own secret when its `signed_with` is `own_secret`) and normal
+signature verification. The CLI never forwards your API credentials. It does not follow
 redirects or disable TLS verification. A response must finish within 30 seconds
 and remain within 1 MiB. Existing confirmation headers retain their meaning,
 including account content-discard behavior; exec and stdout do not confirm
@@ -218,15 +219,15 @@ boundary to at most 60 characters. The whole message is the body.
 
 ## Authentication
 
-Use `primitive signin` or `primitive login` for existing accounts. With no email, both use browser approval; `primitive signin browser` and `primitive login browser` are the explicit browser forms.
+Use `primitive signin` or `primitive login` to log in. With no email, both use browser approval; `primitive signin browser` and `primitive login browser` are the explicit browser forms.
 
-Use `primitive signin <email> --accept-terms`, then `primitive signin confirm <email> <code>` for email-code sign-in. `primitive login <email>` and `primitive otp <email>` support the same email-code flow with matching `confirm` and `resend` subcommands.
+Use `primitive signin <email> --accept-terms`, then `primitive signin confirm <email> <code>` for email-code sign-in. `primitive login <email>` and `primitive otp <email>` support the same email-code flow with matching `confirm` and `resend` subcommands. The code logs you in to the account that uses the address, or creates a new account when none does. Primitive sends no emailed code to an address on a domain it receives mail for; log in with `primitive login browser` instead. Without a terminal to answer the terms prompt, these commands stop and ask for `--accept-terms`.
 
 Use `primitive logout --force` to remove local CLI credentials, pending email-code auth state, and stale credential locks without contacting Primitive. This is the recovery command when an interrupted auth command leaves the CLI saying another credential operation is already in progress.
 
-Use `primitive org leave` to leave the organization you are signed in to. It asks for confirmation first; pass `--yes` to skip the prompt in scripts. Leaving is final. Only a person signed in with `primitive login` can leave; API keys are refused. The only owner of an organization cannot leave it until someone else is made an owner. If the server asks you to confirm in the dashboard, the command prints the confirmation page and, in a terminal, asks for the token it shows; in a script, pass the token with `--step-up-token`. Refusals from the server are printed as returned, and the command exits 1.
+Use `primitive org leave` to leave the organization you are signed in to. It asks for confirmation first; pass `--yes` to skip the prompt in scripts. Leaving is final. Only a person signed in with `primitive login` can leave; API keys are refused. The only owner of an organization cannot leave it until someone else is made an owner. If the server asks you to confirm in the dashboard, the command prints the confirmation page and, in a terminal, asks for the token it shows; in a script, pass the token with `--step-up-token`. Refusals from the server are printed as returned, and the command exits 1. Without a terminal and without `--yes`, it exits 2 before anything is sent.
 
-Use `primitive signup <email>` for new account creation, then `primitive signup confirm <email> <code>` with the emailed verification code. Non-interactive signup is available with `--accept-terms`.
+Use `primitive signup <email>` for new account creation, then `primitive signup confirm <email> <code>` with the emailed verification code. Without a terminal, pass `--accept-terms`.
 
 ### Switching organizations
 
@@ -246,20 +247,29 @@ Against a server without organization switching, and for logins saved by earlier
 
 ### Grants and keys
 
-`primitive whoami` shows your organization, role and grant when the server reports them. `primitive whoami --check mail:send` asks whether the current credential may use a permission, prints the decision, and exits 1 when it may not; nothing is enforced by asking. A request refused because the credential's grant lacks a permission fails with `grant_forbidden`, and the CLI names the permission.
+`primitive whoami` shows your member address, your organization, your built-in role and the credential's grant when the server reports them; only a person's own login has a role line. `primitive whoami --check mail:send` asks whether the current credential may use a permission, prints the decision, and exits 1 when it may not; nothing is enforced by asking. A request refused because the credential's grant lacks a permission fails with `grant_forbidden`, and the CLI names the permission.
 
 ```bash
 primitive keys list
-primitive keys list --json
+primitive keys get <id> --json
+primitive keys create --name orders --permission mail:read --rule <rule-id>
+primitive keys update <id> --add mail:send,mail:reply
+primitive keys update <id> --expires-at 2027-02-08T00:00:00Z
+primitive keys rotate <id>
+primitive keys revoke <id>
 ```
 
-`keys list` shows each key's id, prefix, name, grant, expiry and last use. It never shows a secret. API keys are created, rotated and revoked in the dashboard for now. CLI commands for this are planned. `keys list` uses the credential inventory, which the server answers only for an owner or admin in a dashboard session, so from the CLI it shows the server's refusal.
+`keys list` shows each key's id, prefix, name, permissions, the mail it reaches, expiry and last use, and `keys get` shows one key in full. Neither shows a secret. Revoked keys are left out of `keys list` unless you pass `--include-revoked`, which marks each `[revoked]` with when it was revoked. You see your own keys, and every key if your role may read them all.
 
-`primitive roles list`, `primitive roles groups`, `primitive roles mailbox-access` and `primitive roles access-mode` read roles, groups, mailbox access and the access mode. Where the server has not enabled them, they print `feature_disabled`. The built-in roles are `owner`, `admin`, `operator` and `member`. `operator` has every permission `admin` has except managing members, changing roles, sending invitations and billing. By default, owners, admins and operators may use the CLI. An organization can open it to every member by setting `cli_access` to `all_members` in its credential policy.
+`keys create` needs you to say what the key can do: a `--preset`, or `--permission` with the mail it reaches (`--address`, `--domain`, `--rule`, each repeatable, or `--all-mailboxes`). There is no default, and a super admin key needs `--preset super_admin`. A key never holds more than you do, and your organization's credential policy applies. `keys update` adds or removes permissions (`--add`, `--remove`), adds or removes email rules (`--add-rule`, `--remove-rule`), or replaces them all (`--rule`); the key keeps its id and secret. A request already held open with that key, such as a long poll or a wait, ends once when its permissions change. `keys update --expires-at <time>` extends a key before it expires, within your organization's credential policy, and `--no-expiry` removes its expiry where the policy allows. Rotating keeps the expiry: `keys rotate` gives the new key the old key's expiry unless you pass `--expires-at` or `--no-expiry`. An expired key cannot be extended.
+
+Creating, rotating and changing a key run directly. If your organization requires approval, the command prints the approval link, opens it where it can, and waits for the one-time token the page shows. In a script it prints the link and exits: approve, then run it again with `--step-up-token`. The new secret is printed once, alone on stdout (or in the JSON with `--json`), and the CLI never saves it, so store it right away. `keys revoke` asks for confirmation; pass `--yes` in scripts.
+
+`primitive roles list`, `primitive roles groups`, `primitive roles mailbox-access` and `primitive roles access-mode` read roles, groups, mailbox access and the access mode. `primitive roles members` (also `primitive members list`) lists the members and their roles. Where the server has not enabled them, they print `feature_disabled`. The built-in roles are `owner`, `admin` and `member`. Operator is a template with every permission `admin` has except managing members, changing roles, managing mailbox delegations, sending invitations and billing. By default, owners, admins and operators may use the CLI. An organization can open it to every member by setting `cli_access` to `all_members` in its credential policy.
 
 ### Trying the preview
 
-Install the 3.0.0 preview with `npm install -g primitive@preview`. `npm install -g primitive` stays on the latest stable version.
+Install the 3.0.0 preview with `npm install -g primitive@preview`. `npm install -g primitive` stays on the latest stable version. Code that uses the SDK alongside the preview CLI, such as a webhook handler reading `email.analysis.understanding`, needs the preview SDK too: `npm install @primitivedotdev/sdk@preview`, or the Python and Go previews their READMEs name. The 2.x SDK does not type the email rules payload.
 
 ### Downgrading after signing in as yourself