@userreason/cli 0.1.0 → 0.1.1

package/README.md

@@ -1,70 +1,123 @@
-# @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
-userreason query --workspace WORKSPACE_UUID --site SITE_UUID --resource surveys --limit 50 --json
-userreason command --file survey-command.json --json
+npx --no-install userreason login --open --credential-store keychain
 ```
 
-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 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.
 
-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.
+## Environments
 
-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.
+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.
 
-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.
+See [troubleshooting](https://docs.userreason.com/get-started/troubleshooting/)
+for installation, sign-in and configuration help.

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 };
+}