@userreason/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,70 +1,330 @@
-# @userreason/cli
+# UserReason CLI
 
-The public CLI uses the same authenticated onboarding API as the dashboard and MCP. This source package is prepared for publication; the npm package is not published by building it.
+Manage UserReason surveys, audiences and feedback from your terminal. Use the CLI
+for product investigations, repeatable workflows and tools that need structured
+JSON output.
+
+[Documentation](https://docs.userreason.com/cli/) ·
+[Get started](https://docs.userreason.com/get-started/quickstart/) ·
+[Dashboard](https://dash.userreason.com)
+
+## Requirements
+
+- Node.js **22.12 or later** and npm, pnpm or Yarn.
+- A UserReason account with access to the workspace you want to manage.
+- A browser to sign in and approve access on your first connection.
+
+## Get started
+
+Run the CLI without a global installation:
 
 ```sh
-npm ci
-npm test
-node dist/bin.js --help
+npx -y @userreason/cli@latest login --open
+npx -y @userreason/cli@latest whoami
 ```
 
-After publication:
+Sign in in the browser, then review the workspaces and permissions you want to
+allow. Each command respects both the approved access and your current workspace
+role.
+
+For a project that already uses UserReason, install the CLI as a development
+dependency:
 
 ```sh
-npx -y @userreason/cli@latest login --open
-npx -y @userreason/cli@latest whoami --json
+npm install --save-dev @userreason/cli
+npx --no-install userreason login --open
+npx --no-install userreason prompt list
 ```
 
-The CLI discovers the public WorkOS client ID from `/onboarding/v1/auth-config` when no override, environment value or saved configuration exists. Discovery is bounded, timed out, environment checked and never follows redirects or receives authentication secrets. The public client ID is configuration, not a secret; `--client-id` or `UR_WORKOS_CLIENT_ID` can override it. `--dev` selects `https://api-dev.userreason.com` and uses `UR_WORKOS_DEV_CLIENT_ID` when provided. Production defaults to `https://api.userreason.com`. `--api-url` accepts HTTPS origins or loopback HTTP for local development. Successful login saves nonsecret client/API configuration separately for each environment.
+The [installation wizard](https://www.npmjs.com/package/@userreason/wizard) can
+install the SDK and project CLI together. For pnpm or Yarn projects, use
+`pnpm exec userreason` or `yarn exec userreason` after installation.
 
-Login uses [WorkOS CLI Auth](https://workos.com/docs/authkit/cli-auth): a public device client confirms a code in the browser, polls at the prescribed interval and receives access/refresh tokens. No WorkOS API key, client secret or UserReason signing key is required. Device codes and tokens are never printed.
+## Work with your project
 
-Credentials live in macOS Keychain, Windows Credential Manager or Linux Secret Service through `@napi-rs/keyring`. There is no plaintext fallback. If the store is unavailable, enable it before logging in. Rotating refresh-token exchanges are serialized across CLI/wizard processes. Credentials are separated by API origin and WorkOS client ID. On provider outages, stored credentials are retained; a revoked/expired refresh grant requires a new login.
+From an application directory, the CLI detects a supported, literal
+`UserReason.init({ siteId: '…' })` configuration and selects that site's workspace.
+You can also choose a target explicitly:
 
-Authentication does not grant workspace or site access to an agent. A human approves a local UserReason grant through the dashboard:
+```sh
+npx --no-install userreason site list --workspace WORKSPACE_UUID
+npx --no-install userreason prompt list --workspace WORKSPACE_UUID --site SITE_UUID
+npx --no-install userreason results overview --workspace WORKSPACE_UUID --site SITE_UUID
+```
+
+`whoami` shows your selected API, account, access and detected project. Projects
+with dynamic or multiple SDK configurations need explicit `--workspace` and
+`--site` flags.
+
+Surveys use the `prompt` command group. For example, `prompt list` lists surveys
+and `prompt responses` reads their responses. Audience, event, user and results
+commands provide the related targeting and reporting tools.
+
+## Find commands and documentation
 
 ```sh
-userreason grant request \
-  --scope workspace:create \
-  --scope workspace:read \
-  --scope site:create \
-  --scope site:read \
-  --scope site:update \
-  --wait
-
-userreason workspace create --name "Acme" --json
-userreason site create \
-  --workspace WORKSPACE_UUID \
-  --name "Acme application" \
-  --origin https://app.example.com \
-  --environment production \
-  --json
+npx --no-install userreason --help
+npx --no-install userreason prompt --help
+npx --no-install userreason docs search "survey targeting"
+npx --no-install userreason docs get /sdk/events/
 ```
 
-An account-level workspace-creation grant permits one creation. The backend binds its remaining permissions to the new workspace and removes `workspace:create`. Creating another workspace requires another approval. For an existing workspace, include `--workspace WORKSPACE_UUID` when requesting a grant. Use `--site SITE_UUID` to request site restrictions. Survey editing and campaign publishing have separate scopes and are not requested by installation.
+The CLI's documentation commands read the current public documentation. When a
+network request is unavailable, they can fall back to the bundled CLI reference;
+`--live` requires an online result and `--offline` selects the bundled reference.
+See the [command reference](https://docs.userreason.com/cli/) for schemas, flags,
+examples and the permissions required by each operation.
 
-Use `--request-id UUID` and `--workspace-id UUID` or `--site-id UUID` to make externally orchestrated creation retries deterministic. Reuse the exact payload and IDs on retry. Default IDs are generated once per command and preserved across an access-token refresh; separate command invocations generate new IDs.
+## Automation and agents
 
-`--json` emits a single JSON result on stdout. Browser links, login instructions and errors use stderr. A nonzero exit code means the command failed. An authorization-required error may contain an `approval_url`; request and approve the required scope before retrying. The `x-ur-client` header is a transport hint: the Worker derives identity and grant binding from the verified token.
+Add `--json` for structured output:
 
 ```sh
-userreason workspace list --json
-userreason site list --workspace WORKSPACE_UUID --json
-userreason grant status --id REQUEST_UUID --wait --json
-userreason logout
+npx --no-install userreason prompt list --json
+npx --no-install userreason results overview --json
 ```
 
-Approved agents can also use the delegated management endpoints:
+Successful JSON results use stdout. Errors and interactive sign-in instructions
+use stderr, and failed commands exit with a nonzero status. `--help --all` shows
+the complete command reference.
+
+The package includes a [UserReason agent skill](skills/userreason/SKILL.md) for
+feedback investigations and approved management workflows. The installation
+wizard can add it to a project's `.agents/skills/` directory after review.
+
+## Access and credentials
+
+`login --open` connects your account and opens access review. Use `access --open`
+to renew or change an existing connection. Access is time-limited, and you can
+revoke a connection in the dashboard. Reading feedback and publishing changes
+require their respective permissions.
+
+Credentials are stored outside your project in a per-user file by default, with
+owner-only permissions on POSIX systems. To use macOS Keychain, Windows
+Credential Manager or Linux Secret Service instead, run:
+
+```sh
+npx --no-install userreason login --open --credential-store keychain
+```
+
+The optional OS credential-store binding must be available for this option. The
+CLI does not fall back to file storage when Keychain storage is explicitly
+selected. `logout` removes credentials from the selected local store; revoke the
+connection in the dashboard to withdraw server access. Never commit credentials
+to your application repository.
+
+## Environments
+
+The CLI connects to the production UserReason API and public documentation by
+default. A customer's development or preview site can still use this API; a
+site's environment is separate from the API environment.
+
+See [troubleshooting](https://docs.userreason.com/get-started/troubleshooting/)
+for installation, sign-in and configuration help.
+
+## Optional usage measurement
+
+The CLI reports canonical command types, success/failure counts, durations,
+execution mode and its version to the UserReason API. It never reports command
+arguments, documentation searches, file paths, source code, command output,
+raw errors, email addresses or credentials as analytics properties. Signed-in
+requests can be associated with the verified UserReason account and workspace;
+anonymous usage uses a random local installation ID. Switching accounts never
+attributes an earlier account's queued activity to the next account.
+
+Usage is batched in the per-user UserReason configuration directory, outside
+your project, with a seven-day expiry, bounded storage and an upload deadline of
+500 ms for anonymous batches or 1.5 seconds for authenticated batches. Failed
+uploads do not change command output or exit status.
+`--offline` sends no analytics requests. Local command discovery (`cli`) also
+stays offline. The queue is retried on later online commands; aggregated command
+counts, rather than the number of batches, describe usage.
+
+Disable for one invocation with `--no-telemetry`, for a process or CI job with
+`UR_TELEMETRY_DISABLED=1` (or `DO_NOT_TRACK=1`), or persistently with:
 
 ```sh
-userreason query --workspace WORKSPACE_UUID --site SITE_UUID --resource surveys --limit 50 --json
-userreason command --file survey-command.json --json
+userreason telemetry disable
+userreason telemetry status
+userreason telemetry enable
 ```
 
-The command file is a versioned management command with `action`, `workspace_id`, `request_id`, site/resource IDs and its action-specific fields. Edits/publishing/deletion also require the current `expected_revision` where defined by the API. The CLI streams at most 64 KB from the local JSON file, and the server validates the complete command and enforces the exact action's scope. Reuse the unchanged file/UUIDs for a retry. Commands named `*.delete` archive or disable records; responses and published versions remain immutable. Workspace/site creation uses the dedicated onboarding commands instead.
+The persistent setting is shared with the installation wizard. Disabling it
+also removes locally queued analytics and the random installation identity.
+
+### Schedule a survey and set collection targets
+
+The JSON definition accepted by `prompt create` and `prompt update` supports an
+optional `rules.collection` object. For example:
+
+```json
+{
+  "starts_at": "2026-10-20T07:00:00.000Z",
+  "ends_at": "2026-10-27T16:00:00.000Z",
+  "time_zone": "Europe/Amsterdam",
+  "response_target": 500,
+  "daily_response_target": 50
+}
+```
+
+Publish the saved draft through the normal prompt command. Use null for an unset
+timestamp or unlimited target, or omit the object for no schedule/targets. Targets
+are shared across the campaign's versions, experiments and enrollments. They stop
+new admissions while allowing already-admitted surveys to finish. `prompt list`
+and prompt reads include the current collection state and completed counts.
+
+## Conversational surveys (development)
+
+The development API accepts a terminal conversation as a text question with a
+versioned `conversation` setting. Use the existing `prompt create`, `update`,
+`validate` and `publish` commands with the complete definition. Read
+`https://docs-dev.userreason.com/prompts/conversations/` for the current schema.
+A conversation stands alone or starts an experiment version; it cannot follow a
+rating. Quick, Focused and In-depth presets limit follow-ups and time. Review and
+Send remain separate: only the visitor's accepted answer is a response.
+
+```sh
+userreason workspace ai get --dev --workspace WORKSPACE_UUID
+userreason workspace ai get --dev --workspace WORKSPACE_UUID --site SITE_UUID
+userreason workspace ai set --dev --workspace WORKSPACE_UUID --file AI-SETTINGS.json
+userreason results conversations PROMPT_UUID --dev --workspace WORKSPACE_UUID --site SITE_UUID
+userreason conversation get CONVERSATION_UUID --dev --workspace WORKSPACE_UUID --site SITE_UUID
+```
+
+`AI-SETTINGS.json` contains only the fields to change, for example
+`{"enabled":true,"voice_enabled":false}`. Owners and admins manage allowance
+controls. To change site context, pass one `--site` and a file such as
+`{"product_context":"Scheduled reports email PDF or CSV files."}`; editors can
+update that site context. Missing settings keep their current value.
+
+Typed, spoken and live-test sessions share workspace AI allowance. Scripted
+preview uses no allowance. Accepted text, transcript, and optional generated
+analysis have different provenance; generated analysis is not a visitor answer.
+These commands require the matching development backend and private development
+package set. Public npm `latest` remains unchanged by this rollout.
+
+## Browser setup client and local execution
+
+The exported setup-v1 client provides a proof-bound handshake, strict bounded
+protocol reads, heartbeat/claim/result adapters and `runSetupExecutor` with a per-project lock for the
+browser-driven wizard. It uses a separate owner-only `setup-v1` store
+outside the project; it neither reads nor replaces normal login credentials.
+Loading a selected expired setup removes its capability. New setup saves lazily
+inspect at most 128 directory entries and remove validated setup records at
+least seven days old; later saves handle remaining batches. There is no cleanup
+daemon. Unknown files, symlinks, project files, locks and normal login credentials
+are left alone.
+The server must explicitly advertise `browser_setup` v1 as enabled. Old or
+disabled servers return an unsupported result before local effects. A started
+setup never silently falls back to a different installation flow.
+
+Setup requests also propagate `--no-telemetry`, the shared saved opt-out,
+`UR_TELEMETRY_DISABLED` and `DO_NOT_TRACK` to optional server-side setup
+measurement. Unreadable preference state suppresses measurement without blocking
+the setup request. Browser measurement preferences remain separate.
+
+An active setup can request its simulated sample using:
+
+```sh
+userreason setup sample --setup SETUP_UUID --directory /path/to/original/project --json
+```
+
+Use `--api-url` or `--dev` for the same API as that setup. This operation requires
+its unexpired local setup capability and an open sample-test step. It reads a
+clearly labelled static sample and records only that setup's read receipt; it
+does not read real feedback, create responses, consume response quota, publish
+surveys or authorize ongoing CLI access. The ID in the command is not a bearer
+credential. Setup credentials are never printed. `--request-id UUID` permits an
+explicit idempotent retry of the read.
+
+The executor accepts only locally prepared, browser-approved typed operations.
+It writes a private intent before starting, verifies exact source/manifest hashes,
+and records the result before reporting. Package-manager lockfiles are declared
+managed outputs: their contents are generated during dependency resolution and
+their actual hashes are saved in the local receipt, rather than predicted.
+After an interruption it reconciles known output; it never blindly reruns an
+unknown command. `recoverSetupProjectLock` explicitly releases a crashed owner's
+lock only after that process is gone. Local receipts contain prepared file bytes,
+stay outside the project with owner-only permissions, and expire after seven
+days. Lazy cleanup is bounded; receipts never restore expired remote access.
+The browser executor requires durable file synchronization (`fsync`). Node 24
+permission mode disables that operation even for allowed paths, so setup stops
+before server calls or application changes under those flags. It does not remove
+permission flags or fall back to nondurable receipts.
+
+`detectSetupTerminal` emits fixed platform/app codes only. Installing the project
+agent skill does not grant continuing management access. Ordinary CLI login,
+terminal installation and first-survey commands are unchanged.
+
+`runBrowserSetup` connects this executor to the optional browser onboarding flow.
+The server's source-analysis flag is checked before collecting any source. The
+local collector prepares a bounded, memory-only application packet with no Git
+history. `onSourcePrepared` can display the exact excerpts locally; the initial
+`source-plan` request contains only relative paths, line ranges, hashes and package
+metadata. The browser separately approves that packet digest and configured
+providers. Immediately before `source-upload`, the runner rechecks all full-file
+hashes, recollects the same snapshot and validates installed package metadata.
+Source text is never saved in setup receipts. Resuming rebuilds the original
+snapshot ID and refuses changed content until the browser reviews a fresh packet.
+
+Heartbeat continues while the bounded analysis request runs. A dropped response
+is reconciled by polling, not a repeated provider call. A failed preparation or
+analysis needs a browser retry or skip. The browser owns candidate selection,
+inactive draft creation, sample skip, finish and cancellation. The local runner
+cannot create drafts, publish surveys or change ongoing CLI grants. Server rollout
+flags remain off by default; these are prepared clients for a compatible release.
+
+## Optional first-survey guidance
+
+The development wizard also uses the exported `starterSurvey` flow. It provides
+one-question starters for improvement, workflow friction and satisfaction, with
+optional background personalization. Local preparation after sign-in is
+memory-only; provider processing still needs approval of the exact source packet.
+The model returns wording and cited rationale, while the Worker compiles the
+inactive draft. Users keep control of their edits and choose delivery separately.
+An unconfigured starter matches nobody, even if it is later published unchanged.
+Draft save receipts survive a lost response so retries use the same identifiers.
+This does not change the legacy `first-survey start` command.
+
+`userreason first-survey start --workspace WORKSPACE_UUID --site SITE_UUID
+--directory /absolute/app` offers interactive, evidence-backed suggestions and
+individual unpublished draft creation. Repeating the command resumes the private
+session. `handoff` prints a coding-agent task; `cancel` prevents further work;
+`delete` removes the retained plan (not already-created drafts). No publication
+or source edits are automatic. Noninteractive/JSON runs cannot authorize analysis.
+
+Only a reviewed packet from the explicit application root is uploaded. Default
+bounds: 200 files, 500 KiB local text, 10 KiB source packet, 12,000 input and 4,000
+output tokens, one clarification round. Symlinks, ignored/generated files and
+files with detected secrets are omitted. Detection is best effort: review every
+excerpt. Git subjects need separate consent and are limited to 20 commits/90 days;
+no authors, diffs or network fetch. Narrow the selected paths when truncated.
+
+Before saving, the review shows every question, rating label, answer option and
+conditional route in the returned definition. The analysis deadline is 35 seconds;
+the transport allows the backend's maximum deadline without cutting it off early.
+Draft validation remains authoritative: unsupported survey behavior cannot be
+silently converted or published by this flow.
 
-Queries support `sites`, `surveys`, `campaigns`, `events`, `responses` and `audits`, with a limit of 1–100 and an optional `--after` UUID from the server's `next` field. Site restrictions and current workspace membership are enforced server-side.
+The provider destination and configured policy are shown before approval. Local
+sessions contain hashes, private proposals and mutation receipts, never submitted source
+packets or credentials (generated plans can quote source); protect their owner-only config directory. They expire
+after seven days. Worker plans expire after seven days and are purged on subsequent
+planning activity; provider retention is separately configured/disclosed. Drafts
+have their normal account retention. Deletion retains a content-free budget
+receipt until expiry so it cannot reset allowance. No first-survey content is sent
+to product telemetry.
 
-Logout removes local credentials. Revoke the relevant grant in the dashboard to remove server-side agent access. The packaged [UserReason skill](skills/userreason/SKILL.md) describes agent use of these commands.
+Analysis requires an ongoing connection with `site:read` and `survey:write` on the
+exact site; installation grants do not suffice. Use `access --open` if necessary,
+reviewing replacement-grant semantics rather than broadening installation access.
+Provider errors do not undo installation. Use the agent/manual workflow when
+analysis is unavailable. Integration and browser eligibility remain unverified
+until tested: reachable configuration is not browser verification. Instrumentation
+requires a reviewed, hash-guarded diff and separate edit approval using the agent
+skill; unsupported host transforms are never executed automatically.
 
-The CLI uses `/onboarding/v1/...`; those endpoints require the new migrations, configured WorkOS environment and deployed Worker. Live provider authentication is not exercised by the local fixture tests.
+The 0.2.0 production installation profile selects `@userreason/js@0.5.0` and
+`@userreason/cli@0.2.0` exactly. Browser setup remains an explicit wizard entry
+and requires an enabled compatible server; ordinary CLI authentication and
+management commands retain their existing authorization flow.

package/dist/authorize.d.ts

@@ -0,0 +1,29 @@
+import { UserReasonClient } from './client.js';
+import { type DeviceAuthorization, type Fetch } from './workos.js';
+import { type Credentials, type GrantRequest } from './contracts.js';
+import type { ClientConfig } from './config.js';
+/** Sign in if needed, then obtain fresh, explicit consent. Never silently upgrade an existing grant. */
+export declare function authorizeCli(config: ClientConfig, credentials: Credentials, options: {
+    onDevice: (device: DeviceAuthorization) => void | Promise<void>;
+    onApproval: (request: GrantRequest) => void | Promise<void>;
+    client?: UserReasonClient;
+    fetcher?: Fetch;
+    wait?: boolean;
+    workspaceIds?: string[];
+}): Promise<{
+    authenticated: boolean;
+    api_url: string;
+    request: GrantRequest;
+    user?: undefined;
+    grant?: undefined;
+} | {
+    authenticated: boolean;
+    api_url: string;
+    user: {
+        id: string;
+        email?: string | null;
+        name?: string | null;
+    };
+    grant: import("./contracts.js").Grant | undefined;
+    request: GrantRequest;
+}>;

package/dist/authorize.js

@@ -0,0 +1,23 @@
+import { UserReasonClient } from './client.js';
+import { AuthenticationError, login } from './workos.js';
+import { SCOPES } from './contracts.js';
+/** Sign in if needed, then obtain fresh, explicit consent. Never silently upgrade an existing grant. */
+export async function authorizeCli(config, credentials, options) {
+    const client = options.client ?? new UserReasonClient(config, credentials, { fetcher: options.fetcher });
+    try {
+        await client.account();
+    }
+    catch (error) {
+        const session = await credentials.load();
+        if (session && !(error instanceof AuthenticationError && ['invalid_grant', 'installation_expired'].includes(error.code)))
+            throw error;
+        await login(config, credentials, options.onDevice, { fetcher: options.fetcher });
+    }
+    const request = await client.requestGrant({ allWorkspaces: !options.workspaceIds, workspaceIds: options.workspaceIds, scopes: [...SCOPES] });
+    await options.onApproval(request);
+    if (options.wait === false)
+        return { authenticated: true, api_url: config.apiUrl, request };
+    const decision = await client.waitForGrant(request.id);
+    const account = await client.account();
+    return { authenticated: true, api_url: config.apiUrl, user: account.user, grant: account.grants.find(grant => grant.id === decision.grant_id), request: decision };
+}