primcli 1.26.0 → 1.29.0

package/README.md

@@ -206,6 +206,24 @@ primitive memories get state --function <function-id>
 Values must be valid JSON. Strings must be quoted as JSON strings, so use
 `'"hello"'`, not `hello`.
 
+## Credits
+
+Redeem a credit code for your organization and check the credit balance.
+
+```bash
+primitive credits redeem LAUNCH50
+primitive credits balance
+primitive credits balance --json
+```
+
+`credits redeem` prints the credit added and its expiry. On a refusal it prints
+the server's message (for example an invalid or already redeemed code) and
+exits non-zero. Redeeming needs an organization owner or admin; with an API key,
+the key's creator must currently be an owner or admin. Each run sends a new
+Idempotency-Key; pass `--idempotency-key <key>` to retry the same redemption
+safely. On any failure the command prints the key it used to stderr, so you can
+run the same command again with `--idempotency-key <key>`.
+
 ## Recipient routing
 
 Bind a recipient address to a destination so inbound mail resolves to a single
@@ -300,3 +318,34 @@ The CLI previously shipped inside `@primitivedotdev/sdk`. The shipped surface ar
 ## License
 
 MIT
+
+### Local event listening
+
+```sh
+primitive listen --forward-to localhost:3000
+primitive listen --forward-to 3000 --events email.received
+primitive listen --once --timeout 60
+primitive listen --subscription my-agent --exec "python3 accept.py"
+```
+
+WebSocket is the default transport. Subscription registration and reconnects are
+automatic; the saved default resumes the same durable queue. `--once` waits for
+one successful, confirmed delivery. `--timeout` is in seconds and exits 2 on
+timeout; Ctrl-C exits 130. Bare `primitive listen` prints one raw JSON event per
+line. Use `--transport poll` explicitly for HTTP polling. Accept or enqueue each
+event within 30 seconds. Closing preserves pending work, and retries can deliver
+an event more than once.
+
+### Connected-agent listeners
+
+Use the agent's existing connected-address credential with the same listener API.
+The server automatically restricts its private subscription to inbound email for
+that address. No owner credential, recipient filter, or relay is required. Names
+are isolated per credential. Revoking or replacing the credential removes its
+subscriptions and queued deliveries; reconnect with the new credential to start
+receiving new events.
+
+Address-scoped events contain parsed message content in `email.parsed`.
+`email.content.raw` and `email.content.download` are null. Signed download links,
+account routing metadata, and other SMTP envelope recipients are not exposed.
+Attachments can be fetched through the authenticated email attachment API.