primcli 1.22.0 → 1.24.0

package/README.md

@@ -1,4 +1,4 @@
-# @primitivedotdev/cli
+# primitive
 
 Official Primitive CLI. Deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal.
 
@@ -10,24 +10,116 @@ primitive whoami
 Or with npm:
 
 ```bash
-npm install -g @primitivedotdev/cli
+npm install -g primitive
 primitive whoami
 # `prim` is installed as a short alias for the same CLI.
 prim whoami
 ```
 
-The same CLI is also published unscoped as [`primcli`](https://www.npmjs.com/package/primcli). `npm install -g primcli` installs an identical build with the same `primitive`/`prim` commands. Use whichever name you prefer; they track the same version.
+The same CLI is also published as [`primcli`](https://www.npmjs.com/package/primcli) and under the legacy scoped name [`@primitivedotdev/cli`](https://www.npmjs.com/package/@primitivedotdev/cli). Each installs an identical build with the same `primitive`/`prim` commands. Use whichever name you prefer; they track the same version.
 
 Or with no install:
 
 ```bash
-npx @primitivedotdev/cli@latest <command>
+npx primitive@latest <command>
 ```
 
 This package wraps the [@primitivedotdev/sdk](https://www.npmjs.com/package/@primitivedotdev/sdk) runtime client with one-shot commands. For in-handler use (calling Primitive from inside a Function), import `createPrimitiveClient` from `@primitivedotdev/sdk/api` directly; the CLI is for operator and deploy workflows.
 
 ## Quickstart
 
+### Receive webhook events without a public endpoint
+
+With an existing Primitive account and inbox, sign in or set `PRIMITIVE_API_KEY`.
+Run `primitive listen` to print existing webhook events as JSONL. Status goes to
+stderr. No public URL or separate destination setup is required.
+
+For an agent, use a short hook that saves each event into its durable inbox:
+
+```sh
+primitive listen init --language python
+cd primitive-listener
+primitive listen --subscription my-agent --exec 'python3 accept_event.py'
+```
+
+The starter works locally and refuses to overwrite an existing directory. Its
+SQLite inbox is application-owned example code. Replace `accept_event` with your
+agent's existing durable input function. Exit 0 means the input was saved; run
+model work separately so the listener can keep receiving while the agent thinks.
+The hook has a 30-second deadline. Do not spawn a background agent from the hook.
+`--exec` requires macOS or Linux for process-group cleanup. On Windows, use
+`--forward-to` with your agent's local HTTP acceptance handler.
+
+The CLI passes the unchanged event body on stdin, plus `PRIMITIVE_EVENT_ID`,
+`PRIMITIVE_DELIVERY_ID`, and `PRIMITIVE_EVENT_TYPE` in the hook environment.
+Deduplicate by `PRIMITIVE_EVENT_ID`, which stays the same on redelivery. Delivery
+IDs identify individual attempts. Related events need not contain an email or a
+body-level event ID. The generated processing example shows existing Python SDK
+conversation and reply calls; sending requires an explicit choice.
+
+To run an existing HTTP webhook handler locally:
+
+```sh
+primitive listen --subscription local-webhook --forward-to http://localhost:3000/webhook
+```
+
+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
+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
+content discard.
+
+Use `--events email.received,interaction.ack.received` to select events on a new
+subscription. Omitting `--events` when resuming preserves its selection. A
+conflicting selection requires a different subscription name. Ctrl-C disconnects
+without deleting the destination; restart with the same name to receive pending
+events. On the same machine, a second listener cannot consume that subscription
+while the first holds it. The same name on different machines shares consumption;
+different names receive independent copies. With no name, the CLI saves a private
+default identity scoped to your API host and account.
+
+`--number N` exits after N successful, server-confirmed completions. A crash after
+the hook saves input but before completion can redeliver it. Bare stdout is for
+inspection: a successful pipe write does not prove a downstream agent saved the
+event. Use the durable hook for ingestion.
+
+The server retains pending references for 24 hours, subject to source-content
+availability and queue capacity. The listener reports delivery gaps instead of
+silently claiming it is caught up. Saving download links does not preserve
+attachment bytes or extend their expiry. To remove a destination, use its ID from
+the readiness message: `primitive endpoints delete --id DESTINATION_ID`.
+
+### Low-level delivery API
+
+The generated `endpoints pull-webhook-event` and `endpoints complete-webhook-event`
+commands expose the local-delivery API when enabled on your API host. These are
+single API calls; a receive loop must retain the destination identity and report
+each attempt's outcome. Use `--help` to inspect the request fields:
+
+```sh
+primitive endpoints pull-webhook-event --help
+primitive endpoints complete-webhook-event --help
+```
+
+Completion uses a mode-specific JSON body. For a successful process handler:
+
+```sh
+primitive endpoints complete-webhook-event --id ENDPOINT_ID --raw-body '{"queue_id":"QUEUE_ID","delivery_id":"DELIVERY_ID","lease_token":"LEASE_TOKEN","mode":"exec","exit_code":0,"duration_ms":12}'
+```
+
+Use the IDs and lease token returned by pull. HTTP forwarding reports
+`mode: "http"` with `status_code`; stdout reports `mode: "stdout"` with
+`write_succeeded`. Transport failures must also be reported. Successful handler
+acceptance is separate from any later agent reasoning.
+
+Pull delivery preserves existing webhook bodies and supplies canonical event and
+attempt IDs separately. Deduplicate by event ID. A successful completion can be
+retried with the same queue, attempt, token, and outcome. Check the returned gap
+count as well as the backlog; queue retention does not extend email-content
+retention. Conversation retrieval and threaded replies use the existing SDK API.
+
 ```bash
 primitive signin
 primitive whoami
@@ -124,10 +216,11 @@ The `primitive payments` command group drives non-custodial x402 USDC payments.
 # ownership message locally with your wallet key. Org is auto-resolved.
 primitive payments register-payout-address --network base-sepolia --label treasury
 
-# Payee: request a payment with a human USDC amount. Prints a summary by default.
+# Payee: request a payment with a human USDC amount. Prints the challenge JSON
+# to stdout; a one-line summary goes to stderr.
 primitive payments charge --network base-sepolia --amount-usdc 0.01
-# Capture the raw challenge JSON to hand to the payer.
-primitive payments charge --network base-sepolia --amount-usdc 0.01 --json > challenge.json
+# Capture the challenge JSON to hand to the payer.
+primitive payments charge --network base-sepolia --amount-usdc 0.01 > challenge.json
 
 # Payer: sign and settle the challenge locally. Reads the challenge inline,
 # from a file, or piped on stdin.
@@ -164,7 +257,7 @@ primitive payments get-spend-policy
 primitive payments update-spend-policy --max-per-payment 5000000
 ```
 
-`charge` is the friendly verb that matches the SDK `charge` and accepts `--amount-usdc`; `create-challenge` is the lower-level command that takes base-unit `--amount`. Either creates a challenge. The signing commands print a human-readable summary by default; pass `--json` for raw JSON suitable for piping.
+`charge` is the friendly verb that matches the SDK `charge` and accepts `--amount-usdc`; `create-challenge` is the lower-level command that takes base-unit `--amount`. Either creates a challenge. All four signing commands accept `--json`. `register-payout-address` and `pay` print a human-readable summary by default and raw JSON with `--json`; `pay-email` and `pay-email-step` print JSON by default (the send result and the `interaction.json` bytes, respectively), and `--json` switches them to a fuller envelope object.
 
 The signing commands (`register-payout-address`, `pay`, `pay-email`, and `pay-email-step`) need your wallet key. `pay-email` is the recommended payer path for the email-native flow: it signs and sends in one step. `pay-email-step` signs only and emits the `interaction.json` artifact for advanced use where you want to deliver it yourself. Set the key in `PRIMITIVE_X402_PRIVATE_KEY` (a `0x`-prefixed hex private key) so it never lands in shell history or the process list:
 
@@ -172,7 +265,7 @@ The signing commands (`register-payout-address`, `pay`, `pay-email`, and `pay-em
 export PRIMITIVE_X402_PRIVATE_KEY=0x...
 ```
 
-A hidden `--private-key` flag is available as an escape hatch for scripted use, but the environment variable is preferred. The non-signing commands (`charge`, `get-challenge`, `list-payout-addresses`, `get-spend-policy`, `update-spend-policy`) need only your Primitive API key. Run `primitive payments <command> --help` for the full flag list of any command.
+A `--private-key` flag is available as an escape hatch for scripted use, but the environment variable is preferred. The non-signing commands (`charge`, `get-challenge`, `list-payout-addresses`, `get-spend-policy`, `update-spend-policy`) need only your Primitive API key. Run `primitive payments <command> --help` for the full flag list of any command.
 
 ## Migrating from `@primitivedotdev/sdk` CLI
 
@@ -180,10 +273,10 @@ The CLI previously shipped inside `@primitivedotdev/sdk`. The shipped surface ar
 
 | Before | After |
 |--------|-------|
-| `npm install -g @primitivedotdev/sdk` | `npm install -g @primitivedotdev/cli` |
-| `npx @primitivedotdev/sdk@latest <cmd>` | `npx @primitivedotdev/cli@latest <cmd>` |
+| `npm install -g @primitivedotdev/sdk` | `npm install -g primitive` |
+| `npx @primitivedotdev/sdk@latest <cmd>` | `npx primitive@latest <cmd>` |
 
-`@primitivedotdev/sdk` continues to ship the runtime SDK (webhook, API client, contract, parser, openapi). Use it in your application code; use `@primitivedotdev/cli` in your shell and CI.
+`@primitivedotdev/sdk` continues to ship the runtime SDK (webhook, API client, contract, parser, openapi). Use it in your application code; use `primitive` in your shell and CI.
 
 ## License