# CLI product contract **Status:** Approved product contract **Product contract revision:** `2026-08-12.7` **Remote API contract revision:** `2026-08-12.7` **Owner-reviewed baseline:** product and remote `2026-08-12.6` **Currently shipped Go revisions:** product and remote `2026-08-12.7` This document defines the public behavior of the greenfield Go `partiful` CLI. It is the authority for commands, inputs, JSON outputs, failures, and mutation safety. [`spec/partiful.openapi.json`](../spec/partiful.openapi.json) remains the separate authority for remote transport facts. The TypeScript CLI is research evidence only. Its command names, output, credential format, helpers, and quirks are not compatibility requirements. ## Product rules 1. Commands represent Partiful tasks, not remote endpoints. 2. Command results are JSON. Diagnostics go to stderr. 3. Failures have stable types and exit codes. 4. Remote mutations support a redacted `--dry-run` preview and otherwise execute in one invocation. 5. Destructive actions require a TTY confirmation unless `--force` is set. 6. Authentication secrets, phone numbers, email addresses, and Partiful user IDs never appear in command output. 7. Raw Firebase, Firestore, upload, and callable operations are not public. 8. The CLI never guesses when Partiful no longer matches the reviewed remote API contract. ## Invocation and input The command shape is: ```text partiful [subresource] [primary-resource] [flags] ``` The primary resource, such as an event ID, is positional. Common scalar input uses named flags. Commands with structured input accept exactly one of: ```text --input --input - ``` `--input -` reads one JSON object from stdin. Structured input and equivalent field flags cannot be combined. Unknown fields and repeated scalar flags are input errors. Dates and times use RFC 3339. Event writes also require an IANA timezone such as `America/Los_Angeles`. Zone-free dates, natural-language dates, and an implicit default timezone are not accepted. The CLI does not have a product-specific output-file flag. It writes one JSON document to stdout. Callers use shell redirection when they need a file. The CLI finishes the complete result before it writes to stdout, so a failed command does not leave a partial JSON result. Global flags are: | Flag | Meaning | | --- | --- | | `--pretty` | Indent the JSON result without changing its fields. | | `--non-interactive` | Prohibit terminal prompts. This is the default for every command except `auth login`. | | `--no-input` | Prohibit terminal prompts. This is an alias of `--non-interactive`. | | `--version` | Return `{"version","productContractRevision","remoteContractRevision"}` in the success envelope with command `version`. Release builds may inject the version string at link time; development builds use the source default. | `schema` is the machine-readable discovery interface. Help text can guide a human to `schema`, but scripts must not parse help text. ## JSON envelopes Every successful command returns: ```json { "ok": true, "data": {}, "meta": { "command": "events.get", "cliVersion": "3.0.0", "productContractRevision": "2026-08-12.7", "remoteContractRevision": "2026-08-12.7", "warnings": [] } } ``` Every failed command returns: ```json { "ok": false, "error": { "type": "permission.denied", "code": "HOST_PERMISSION_REQUIRED", "message": "This command requires host access to the event.", "retryable": false, "details": { "requiredRole": "host" } }, "meta": { "command": "guests.list", "cliVersion": "3.0.0", "productContractRevision": "2026-08-12.7", "remoteContractRevision": "2026-08-12.7" } } ``` `type` is a stable category for control flow. `code` is a stable specific condition. `message` is for a human. `details` contains only safe structured context. Remote response bodies are not copied into an error. Missing optional values are JSON `null`. Commands do not omit documented fields based on remote response variation. Command examples below show the value inside `data`. The complete `{"ok","data","meta"}` envelope always wraps it. ## Failure and exit contract | Exit | Failure types | Meaning | | --- | --- | --- | | `0` | None | Success. A dry-run preview is also a success because no mutation was attempted. | | `2` | `usage.invalid`, `input.invalid`, `match.ambiguous` | The invocation must change. | | `3` | `auth.required`, `auth.expired`, `auth.human_required` | A human must establish or repair authentication. | | `4` | `permission.denied` | The signed-in account lacks the required role. | | `5` | `resource.not_found` | The selected domain resource does not exist. | | `6` | `state.conflict` | Remote state changed or violates a command precondition. | | `7` | `safety.confirmation_required` | A destructive command requires an allowed confirmation path. | | `8` | `remote.unavailable`, `remote.rate_limited` | Partiful could not complete a known request. `retryable` and retry details are explicit. | | `9` | `contract.protocol_changed` | Partiful no longer matches a reviewed remote mapping. The CLI stops and tells the user to update it. | | `10` | `internal.failure` | An unexpected local failure occurred. | Lack of remote evidence is not a runtime failure. It is an implementation gate: the affected command cannot ship until its required response and failure mappings are reviewed into the remote API contract. ## Collection and pagination contract Collection commands return: ```json { "ok": true, "data": { "items": [] }, "meta": { "command": "events.list", "cliVersion": "3.0.0", "productContractRevision": "2026-08-12.7", "remoteContractRevision": "2026-08-12.7", "warnings": [], "page": { "limit": 25, "nextCursor": null, "hasMore": false } } } ``` Collection commands accept: | Flag | Meaning | | --- | --- | | `--limit ` | Maximum items in this result. The default is `25`; the maximum is `100`. | | `--cursor ` | Continue from a cursor returned by the same command and filters. | | `--all` | Request multiple pages. Requires `--max-items`. | | `--max-items ` | Hard result limit for `--all`; maximum `1000`. | Cursors are opaque. A caller must not inspect, edit, or reuse a cursor with different filters. If the remote capability cannot support this contract safely, the collection command remains behind its implementation gate. When `--all` reaches `--max-items` before the collection ends, `hasMore` is `true` and `nextCursor` lets the caller resume from that exact point. ### Event-list local snapshots `events list` has no remote paging contract. One invocation fetches exactly one reviewed upcoming or past one-response representation and paginates that array locally. The CLI preserves the received sequence without claiming what the remote order means. The local safety ceiling is 1,000 items and 8 MiB for the complete response. If either ceiling is exceeded, the CLI returns `contract.protocol_changed` / `EVENT_LIST_BOUND_EXCEEDED`; it does not truncate a successful result. An event-list cursor is digest-bound to the complete response representation, the `events.list` command, the normalized `--when` value, and the next array offset. Resumption refetches the same one-response representation once. If its digest changed, the CLI returns `state.conflict` / `CURSOR_SNAPSHOT_CHANGED` rather than skip, repeat, merge, or guess items. This is local snapshot pagination. It does not claim a remote cursor, limit, ordering key, snapshot, or future completeness. ## Mutation safety ### Common mutation flags Every remote mutation accepts these flags, regardless of where they appear in the argument list: | Flag | Meaning | | --- | --- | | `--dry-run` | Validate input, perform required read-only resolution and precondition checks, and return a stable redacted preview without dispatching a mutation. | | `--force` | Skip only the TTY prompt for a destructive command. Validation, authorization, precondition checks, and fail-closed handling still run. | | `--no-input` | Never prompt. A destructive command fails with `safety.confirmation_required` unless `--force` is also present. | Without `--dry-run`, one invocation validates its normalized input, performs the required read-before-write checks, and dispatches exactly once. There is no persisted mutation state, confirmation token, expiry window, or automatic retry. A dry-run success contains the operation, normalized public input, redacted public request, and public precondition markers appropriate to the command. It can read remote state needed to resolve names, permissions, or request shape, but it makes zero mutation calls and does not persist refreshed credentials. Authentication secrets, account identifiers, guest IDs, contact IDs, message bodies, and other private remote identifiers never appear in the preview. ### Destructive confirmation These commands are destructive: - `events cancel`; - `cohosts remove`; - `cohosts revoke-invite`; and - `cohosts link revoke`. After validation and required read-before-write checks, a destructive command prompts only when standard input is a terminal. A positive answer dispatches the mutation once. Declining, an input error, `--no-input`, `--non-interactive`, or a non-TTY invocation returns `safety.confirmation_required` and makes no mutation call. `--force` bypasses only this prompt. All other mutations execute without a CLI prompt. Callers can use `--dry-run` for review before a separate normal invocation. ### Completion uncertainty The CLI never automatically retries a mutation. A timeout, connection loss, or other uncertain completion returns a non-retryable `remote.unavailable` result that tells the caller to inspect remote state before another attempt. ## Authentication ### `partiful auth login` This is the only human-interactive command. It privately prompts for the information required by Partiful and returns: ```json { "authenticated": true, "tokenState": "healthy", "expiresAt": "2026-08-11T00:00:00Z" } ``` Phone numbers, verification codes, Firebase tokens, and Partiful user IDs are never accepted through command-line flags and never printed. If no private terminal is available, the command returns `auth.human_required`. ### `partiful auth status` Returns: ```json { "authenticated": true, "tokenState": "healthy", "expiresAt": "2026-08-11T00:00:00Z" } ``` `tokenState` is `healthy`, `expiring`, `expired`, or `missing`. The command does not return identity details or credentials. When stored credentials have a refresh token and are within five minutes of expiry or already expired, `auth status` deterministically refreshes and atomically replaces them before reporting `healthy`. This makes the command a local mutation. A rejected refresh returns `auth.expired`; an unavailable authentication service returns `remote.unavailable`; and an unrecognized released response returns `contract.protocol_changed`. Credentials without a refresh token continue to report `expiring` or `expired`. ### `partiful auth logout` Deletes local credentials and returns: ```json { "authenticated": false, "tokenState": "missing", "expiresAt": null } ``` Token refresh, custom-token exchange, and Firebase account lookup are internal authentication steps. Other commands never start login or prompt. They return an authentication failure so an agent can hand control to a human. Authentication response bodies are limited to 64 KiB. A larger successful or error response does not enter output and fails closed as `contract.protocol_changed`. A successful token lifetime must exceed the five-minute refresh window so login and refresh can return `healthy`. A shorter lifetime fails closed as `contract.protocol_changed` rather than creating a refresh loop. Protected commands never start login and never receive a private terminal. Missing credentials return `auth.required`. Stored credentials that are expired without a usable refresh token return `auth.expired`. A refresh rejected by the reviewed remote mapping also returns `auth.expired`. Unavailable refresh transport returns `remote.unavailable`; an unrecognized released refresh response returns `contract.protocol_changed`. ## Public commands ### Events #### `partiful events list` Inputs: - exactly one of `--when upcoming` or `--when past`; - collection pagination flags. Each `data.items` entry is an `EventSummary`: ```json { "eventId": "evt_example", "title": "Example event", "start": "2026-09-12T19:00:00-07:00", "end": null, "timezone": "America/Los_Angeles", "state": "active", "userRole": "host", "myRsvp": null } ``` For S3 reads, `eventId` is the only non-null event-read field. It comes from the reviewed list item `id`. All other documented event-read fields are nullable because the reviewed remote representation does not establish their universal presence. A missing optional property produces JSON `null`; it does not make an otherwise reviewed response protocol drift. A present property that violates its reviewed type or closed enum is `contract.protocol_changed`. The conditional scalar projection is: | Product field | Reviewed remote property | Null meaning | | --- | --- | --- | | `title` | string `title` | The property is unavailable. | | `start` | string `startDate` | The property is unavailable. | | `end` | string or null `endDate` | The property is absent or explicitly null. | | `timezone` | string `timezone` | The property is unavailable. | | `state` | `status` mapping below | The property is unavailable. | Event state is an exact closed mapping: - `PUBLISHED` → `active`; - `CANCELED` → `cancelled`. `UNSAVED` exists in the current first-party client vocabulary but has no reviewed S3 product mapping. If it appears in a released event-read response, the command returns `contract.protocol_changed`. Role projection uses private current-user identity only for comparison. It never emits an owner ID: - `ownerIds` contains the current user → `host`; - `ownerIds` is present, does not contain the current user, and `guest` is present → `attendee`; - `ownerIds` is present, does not contain the current user, and `guest` is absent → `none`; - `ownerIds` is absent → `null`. Owner membership takes precedence if a representation also has `guest`. `cohost` is reserved in the product enum, but S3 does not emit it. Current first-party assets do not distinguish a primary host from a cohost, so every owner membership maps to `host` until a distinct reviewed field exists. `myRsvp` uses the read-only `EventReadRsvp` enum. It is a lossless, one-to-one normalization and is separate from S5's narrower writable RSVP intent: | Remote guest status | `EventReadRsvp` | | --- | --- | | `READY_TO_SEND` | `ready-to-send` | | `SENDING` | `sending` | | `SEND_ERROR` | `send-error` | | `DELIVERY_ERROR` | `delivery-error` | | `SENT` | `sent` | | `INTERESTED` | `interested` | | `WAITLIST` | `waitlist` | | `MAYBE` | `maybe` | | `DECLINED` | `declined` | | `GOING` | `going` | | `PENDING_APPROVAL` | `pending-approval` | | `APPROVED` | `approved` | | `WITHDRAWN` | `withdrawn` | | `WAITLISTED_FOR_APPROVAL` | `waitlisted-for-approval` | | `REJECTED` | `rejected` | | `RESPONDED_TO_FIND_A_TIME` | `responded-to-find-a-time` | Null `myRsvp` means that no current guest object or status is available. An unknown present guest status is `contract.protocol_changed`, not null. #### `partiful events get ` Returns an `Event`: ```json { "eventId": "evt_example", "title": null, "start": null, "end": null, "timezone": null, "state": null, "userRole": null, "myRsvp": null, "description": null, "location": null, "address": null, "visibility": null, "guestLimit": null, "poster": null, "links": null } ``` The positional input supplies `eventId`. Reviewed conditional `title`, `startDate`, `endDate`, `timezone`, and `status` properties use the same nullable scalar and state mappings as `EventSummary`. The current `getEventInfo` contract does not map owner or guest properties, so `userRole` and `myRsvp` are null for this command. The product boundary requires `result.data.event` to be an object before any nullable field projection occurs. A null, scalar, or array event value returns `contract.protocol_changed`; it is not converted into an all-null successful event. This is a CLI output invariant and does not claim that the remote operation accepts only one top-level variant. `description`, `location`, `address`, `visibility`, `guestLimit`, `poster`, and `links` are unavailable-not-claimed in S3. They are null even if an unreviewed remote property has a similar name. In particular, `links` is `null`, not an empty array; this does not mean that the remote event has no links. A later contract revision can add a field only after its transport shape and product projection are reviewed. `getEventInfo` has this read failure boundary: - `200` uses the nullable projection above; - `404 NOT_FOUND` → `resource.not_found` / `EVENT_NOT_FOUND`; - no response → `remote.unavailable`; - every other unrecognized received status or malformed reviewed property → `contract.protocol_changed`. An unobserved `403` is not `permission.denied`. The permission mapping is deferred until an inaccessible-event response is reviewed. S3 does not call `firestoreGetEvent`; `.5` returned the same `403 PERMISSION_DENIED` for a selected readable event and a synthetic ID, so that operation cannot distinguish permission or existence. S3 also does not call `getCurrentGuest` or `firestoreGetGuest`; the list's conditional inline `guest.status` is the only reviewed guest projection used here. The two list operations accept only their reviewed `200` bodies. No response is `remote.unavailable`; every unrecognized received status is `contract.protocol_changed`. Their remote permission and failure mappings remain unclaimed. #### `partiful events create` Required input is non-empty `title`, RFC 3339 `start`, and an IANA `timezone`. Optional input is `end`, `description`, `location`, `visibility`, `guestLimit`, `links`, and `posterId`. `end` must not be before `start`. `visibility` is `private` by default or `public`. `guestLimit` is a positive integer. `links` is an array of `{"label":"Tickets","url":"https://example.test/"}` objects with an HTTP or HTTPS URL. `posterId` is only an exact built-in ID returned by `posters list` or `posters search`; a path, upload, or arbitrary URL is invalid. The equivalent flags are `--title`, `--start`, `--end`, `--timezone`, `--description`, `--location`, `--visibility`, `--guest-limit`, repeated `--link `, and `--poster-id`. For create, null for any optional structured-input property has the same meaning as omission: no end, description, location, limit, or links; private visibility; and the built-in fallback poster. No optional product null is sent inside `event`. The narrow current-client projection is exact: | Product input | `createEvent.params.event` | | --- | --- | | `title` | `title` | | `start`, `end` | `startDate`, optional `endDate`, normalized to UTC ISO strings | | `timezone` | `timezone` | | `description` | `description`; omission and null both omit it on create | | `location` | `locationInfo: {"type":"freeform","value":}` | | `visibility` | `public` sends `isPublic: true`; `private` omits `isPublic`; separate first-party `visibility` is fixed to `"public"` | | `guestLimit` | `maxCapacity` and `enableWaitlist: false` | | `links` | `customFields` entries with `icon: "link"`, `value: