neatlogs-cli 0.1.0-team-test.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `neatlogs-cli` are documented in this file.
+
+## 0.1.0-team-test.1
+
+- Team-testing prerelease of the NeatLogs public API CLI.
+
+## 0.1.0
+
+- Initial public release of the NeatLogs public API CLI.

package/README.md

@@ -0,0 +1,602 @@
+# NeatLogs CLI
+
+Use the CLI to inspect and manage your NeatLogs projects from a terminal or an automation agent.
+
+## Choose the right credential
+
+```mermaid
+flowchart LR
+  Start{"Who is using the CLI?"}
+  Human["Human"]
+  Agent["AI agent or CI"]
+  App["Application sending traces"]
+  OAuth["Browser login or Device Flow"]
+  ServiceToken["Service-account token"]
+  IngestKey["Ingest credential"]
+  Vault["Stored in the OS credential vault"]
+  SecretStore["Provided by an agent or CI secret store"]
+  AppSecret["Provided to the SDK as an application secret"]
+
+  Start --> Human --> OAuth --> Vault
+  Start --> Agent --> ServiceToken --> SecretStore
+  Start --> App --> IngestKey --> AppSecret
+```
+
+- Humans use browser OAuth or Device Flow.
+- Codex, Claude Code, CI, and other unattended clients use a service-account token.
+- SDKs and applications use an ingest credential to send traces.
+
+## Human quickstart
+
+1. Install the CLI and confirm that it runs.
+
+   ```bash
+   npm install --global neatlogs-cli@team-test
+   neatlogs --help
+   ```
+
+2. Save the host and sign in through your browser.
+
+   ```bash
+   neatlogs profile set work --host '<https-app-origin>'
+   neatlogs --profile work auth login
+   # Remote/headless alternative:
+   neatlogs --profile work auth login --device
+   ```
+
+3. List the projects you can access.
+
+   ```bash
+   neatlogs --profile work projects list
+   ```
+
+4. Save the project you want this profile to use.
+
+   ```bash
+   neatlogs profile set work --host '<https-app-origin>' --project '<project-uuid>'
+   ```
+
+5. Check your identity and read recent traces.
+
+   ```bash
+   neatlogs --profile work whoami
+   neatlogs --profile work traces list --limit 10
+   ```
+
+`profile set` stores non-secret host and project preferences. Login stores the
+OAuth credentials separately in the native operating-system vault.
+
+## Request only the permissions you need
+
+```bash
+# Default read-oriented login
+neatlogs --profile work auth login
+
+# Add only the write permissions required for evaluation work
+neatlogs --profile work auth login \
+  --scope context:read observability:read evaluation:read evaluation:write offline_access
+```
+
+The consent page lists only the permissions requested by this login command.
+`offline_access` allows refresh tokens; it is not an API permission shown by
+`whoami`.
+
+## Agent and CI automation
+
+In **Settings → Service Accounts**, create a dedicated account, bind only the
+required projects and role, and choose the minimum scopes. Inject
+`NEATLOGS_TOKEN` through the agent or CI secret store; environment tokens are
+never written to the OAuth keychain.
+
+```bash
+export NEATLOGS_TOKEN='<service-account-token>'
+export NEATLOGS_PROJECT_ID='<project-uuid>'
+export NEATLOGS_HOST='<https-api-origin>'
+
+neatlogs projects current --json
+neatlogs whoami --json
+neatlogs traces list --limit 10 --json
+```
+
+Revoking the access token immediately stops later requests without disabling
+the service account. `NEATLOGS_API_KEY` remains a legacy fallback; if it and
+`NEATLOGS_TOKEN` are both set, they must contain the same value.
+
+## Credential storage and security
+
+Human login uses Authorization Code with PKCE and an exact `127.0.0.1`
+callback. `--device` explicitly selects Device Flow for a remote or headless
+terminal. OAuth access and refresh tokens are bound to the exact host, issuer,
+and profile, then stored in macOS Keychain, Windows Credential Manager, or
+Linux Secret Service.
+
+The CLI does not consult Git credential configuration and never silently falls
+back to a file. Linux requires libsecret and a running Secret Service
+implementation; the CLI does not fall back to the kernel keyring or a file when
+that service is unavailable. On POSIX, protected plaintext storage is available
+only with `--allow-file-credentials`; it uses directory mode `0700`, file mode
+`0600`, and warns whenever it is used. Windows rejects that option because
+equivalent ACL enforcement is not implemented.
+
+Credentials are never accepted as command-line flags. The CLI never follows
+redirects, executes arbitrary API URLs, or fetches a live API schema. Recognized
+`nloa_`, `nlsa_`, and `nlpk_` prefixes select exactly one credential class; a
+foreign or mismatched prefix is rejected without fallback.
+
+`schema` inspects the release-embedded contract, not active deployment flags.
+Each operation carries `x-neatlogs-operation-gate`; only `always` is enabled by
+default, while every other gate must be enabled by the server before the
+operation is callable.
+
+## Commands
+
+```text
+neatlogs --profile <name> auth login [--device] [--allow-file-credentials] [--scope <scope...>]
+neatlogs --profile <name> auth status
+neatlogs --profile <name> auth logout [--all] [--local-only]
+neatlogs profile list
+neatlogs profile show [name]
+neatlogs profile set <name> --host <https-origin> [--organization <uuid>] [--project <uuid>]
+neatlogs profile use <name>
+# Authenticated profiles must be logged out before deletion.
+neatlogs profile delete <name>
+neatlogs projects current
+neatlogs projects create --organization <uuid> --name <name> [--timezone <iana>] [--idempotency-key <uuid>]
+neatlogs projects update [--name <name>] [--timezone <iana-or-null>] [--idempotency-key <uuid>]
+neatlogs account profile show
+neatlogs notifications preferences show
+neatlogs orgs list [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs orgs get <organization-uuid>
+neatlogs orgs members list <organization-uuid> [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs orgs members get <organization-uuid> <user-uuid>
+neatlogs orgs members update-role <organization-uuid> <user-uuid> --membership-id <membership-uuid> --expected-role owner|admin|member|guest --role admin|member|guest [--idempotency-key <uuid>]
+neatlogs orgs members remove <organization-uuid> <user-uuid> --membership-id <membership-uuid> --expected-role owner|admin|member|guest --confirm <membership-uuid> [--idempotency-key <uuid>]
+neatlogs orgs invitations list <organization-uuid> [--state all|pending|expired] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs orgs invitations invite <organization-uuid> --email <email> --role admin|member|guest [--idempotency-key <uuid>]
+neatlogs orgs invitations resend <organization-uuid> <invitation-uuid> --email <email> [--idempotency-key <uuid>]
+neatlogs orgs invitations revoke <organization-uuid> <invitation-uuid> --email <email> --confirm <invitation-uuid> [--idempotency-key <uuid>]
+printf '%s' "$INVITATION_TOKEN" | neatlogs orgs invitations accept --token-stdin [--idempotency-key <uuid>]
+neatlogs orgs roles list <organization-uuid> --action invitation|member-role-change
+neatlogs orgs audit list <organization-uuid> [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs service-accounts create <organization-uuid> --name <name> --binding <project-uuid=project_admin|project_member|project_viewer> [--binding ...] [--description <text>] [--idempotency-key <uuid>]
+neatlogs service-accounts bindings add <service-account-uuid> --project-id <project-uuid> --role project_admin|project_member|project_viewer [--idempotency-key <uuid>]
+neatlogs service-accounts bindings set-role <service-account-uuid> <binding-uuid> --role project_admin|project_member|project_viewer [--idempotency-key <uuid>]
+neatlogs service-accounts bindings remove <service-account-uuid> <binding-uuid> --confirm <binding-uuid> [--idempotency-key <uuid>]
+neatlogs billing subscription <organization-uuid>
+neatlogs billing plans <organization-uuid>
+neatlogs usage show <organization-uuid>
+neatlogs usage alerts <organization-uuid> [--state all|unread|unacknowledged|unread-and-unacknowledged] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs projects list [--organization <uuid>] [--include-archived] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs skills list [--include-archived] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs skills get <skill-uuid>
+neatlogs skills import --content-stdin [--name <lowercase-kebab>] [--description <text>] [--idempotency-key <uuid>]
+neatlogs skills update <skill-uuid> --body-stdin [--idempotency-key <uuid>]
+neatlogs skills delete <skill-uuid> --confirm <skill-uuid> [--idempotency-key <uuid>]
+neatlogs whoami
+neatlogs alerts list [--enabled all|true|false] [--rule-type threshold|per_event|compound|ingestion_health|metric_threshold] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs alerts get <alert-rule-uuid>
+printf '%s' "$ALERT_JSON" | neatlogs alerts create --body-stdin [--idempotency-key <uuid>]
+printf '%s' "$ALERT_PATCH_JSON" | neatlogs alerts update <alert-rule-uuid> --body-stdin [--idempotency-key <uuid>]
+neatlogs alerts enable|disable <alert-rule-uuid> [--idempotency-key <uuid>]
+neatlogs alerts delete <alert-rule-uuid> --confirm <alert-rule-uuid> [--idempotency-key <uuid>]
+neatlogs alerts history [--alert-rule-id <uuid>] [--start-time <utc>] [--end-time <utc>] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs alerts changes <alert-rule-uuid> [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs detections list [--status active|inactive|all] [--group <uuid>] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs detections get <detection-uuid>
+neatlogs detections hits <detection-uuid> [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs detections history <detection-uuid> [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs detections trends <detection-uuid> --from <utc> --to <utc> [--granularity hour|day|week]
+neatlogs prompts list [--name <exact-name>] [--source <source>] [--label <label>] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs prompts get <prompt-version-uuid>
+neatlogs prompts history <prompt-version-uuid> [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs prompts diff <from-version-uuid> <to-version-uuid>
+neatlogs prompts create (--body-stdin | --name <name> (--content <text> | --content-stdin | --messages <json>)) [--config <json>] [--variables <json>] [--display-name <name>] [--role <role>] [--tags <csv>] [--commit-message <message>] [--idempotency-key <uuid>]
+neatlogs prompts label <prompt-version-uuid> <label> [--idempotency-key <uuid>]
+neatlogs prompts tag-add <prompt-version-uuid> <tag> [--idempotency-key <uuid>]
+neatlogs prompts tag-remove <prompt-version-uuid> <tag> [--idempotency-key <uuid>]
+neatlogs prompts delete <prompt-version-uuid> --confirm <prompt-version-uuid> [--idempotency-key <uuid>]
+neatlogs evals list [--status draft|active|completed|archived|all] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs evals create --body-stdin [--idempotency-key <uuid>]
+neatlogs evals launch <evaluation-uuid> --assign-me [--review-duration <duration>] [--idempotency-key <uuid>]
+neatlogs evals close <evaluation-uuid> --confirm <evaluation-uuid> [--idempotency-key <uuid>]
+neatlogs evals get <evaluation-uuid>
+neatlogs evals form get <evaluation-uuid>
+neatlogs evals form set <evaluation-uuid> --body-stdin [--idempotency-key <uuid>]
+neatlogs evals update <evaluation-uuid> --body-stdin [--idempotency-key <uuid>]
+neatlogs evals progress <evaluation-uuid>
+neatlogs evals items list <evaluation-uuid> [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs evals items get <evaluation-uuid> <item-uuid>
+neatlogs evals assignments list <evaluation-uuid> <item-uuid>
+neatlogs evals review get <evaluation-uuid> <item-uuid> [--assignment-id <uuid>]
+neatlogs evals review draft <evaluation-uuid> <item-uuid> --body-stdin [--assignment-id <uuid>] [--idempotency-key <key>]
+neatlogs evals review submit <evaluation-uuid> <item-uuid> --body-stdin [--assignment-id <uuid>] [--idempotency-key <key>]
+neatlogs evals schedules list [--status draft|active|completed|archived|all] [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs evals schedules get <schedule-uuid>
+neatlogs evals schedules update <schedule-uuid> --batch-schedule <duration> [--idempotency-key <uuid>]
+neatlogs analytics views save --body-stdin [--idempotency-key <uuid>]
+neatlogs feedback create --trace <trace-id> --body-stdin [--idempotency-key <uuid>]
+neatlogs feedback update <feedback-uuid> --trace <trace-id> --body-stdin [--idempotency-key <uuid>]
+neatlogs feedback delete <feedback-uuid> --trace <trace-id> --confirm <feedback-uuid> [--idempotency-key <uuid>]
+neatlogs feedback span-set <span-id> --trace <trace-id> --body-stdin [--idempotency-key <uuid>]
+neatlogs feedback span-delete <span-id> --trace <trace-id> --confirm <span-id> [--idempotency-key <uuid>]
+neatlogs comments create --trace <trace-id> --thread <thread-uuid> --content-stdin [--idempotency-key <uuid>]
+neatlogs comments update <message-uuid> --trace <trace-id> --thread <thread-uuid> --content-stdin [--idempotency-key <uuid>]
+neatlogs comments delete <message-uuid> --trace <trace-id> --thread <thread-uuid> --confirm <message-uuid> [--idempotency-key <uuid>]
+neatlogs integrations providers
+neatlogs integrations list
+neatlogs webhooks create --body-stdin [--idempotency-key <uuid>]
+neatlogs webhooks update <webhook-uuid> --body-stdin [--idempotency-key <uuid>]
+neatlogs webhooks enable <webhook-uuid> [--idempotency-key <uuid>]
+neatlogs webhooks disable <webhook-uuid> [--idempotency-key <uuid>]
+neatlogs webhooks delete <webhook-uuid> --confirm <webhook-uuid> [--idempotency-key <uuid>]
+neatlogs filters list [--limit 1-100] [--cursor <opaque-cursor>]
+neatlogs filters get <saved-filter-uuid>
+neatlogs traces list [--from <rfc3339>] [--to <rfc3339>] [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs traces get <trace-id>
+neatlogs traces export <trace-id> [--format json|markdown|csv]
+neatlogs traces update-metadata <trace-id> --body-stdin [--idempotency-key <uuid>]
+neatlogs traces search <query> [--from <rfc3339>] [--to <rfc3339>] [--workflow <name>] [--session <id>] [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs traces semantic-search <query> [--from <rfc3339>] [--to <rfc3339>] [--workflow <name>] [--session <id>] [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs traces spans list <trace-id> [--status <status>] [--type <type>] [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs traces spans get <trace-id> <span-id>
+neatlogs traces raw-spans <trace-id> [--status <status>] [--type <type>] [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs traces payload <trace-id> <span-id> --fields input[,output,error]
+neatlogs sessions list [--from <rfc3339>] [--to <rfc3339>] [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs sessions get <session-id> [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs sessions export <session-id> [--format json|markdown|csv]
+neatlogs guest-links list [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs guest-links get <guest-link-uuid>
+neatlogs guest-links mint --evaluation <evaluation-uuid> --recipient-email <email> [--idempotency-key <uuid>]
+neatlogs guest-links rotate <guest-link-uuid> [--idempotency-key <uuid>]
+neatlogs guest-links revoke <guest-link-uuid> --confirm <guest-link-uuid> [--idempotency-key <uuid>]
+neatlogs guest context --request-stdin [--cursor <cursor>] [--limit 1-25]
+neatlogs guest submit <item-id> --request-stdin [--idempotency-key <uuid>]
+neatlogs sharing traces get <trace-id>
+neatlogs api-keys list [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs ingest-credentials list [--limit 1-50] [--cursor <opaque-cursor>]
+neatlogs api-keys create --name <name> --scope <scope> [--scope <scope>] [--expires-in-days 1-365] [--rate-limit 1-600]
+neatlogs api-keys rotate <credential-uuid> --confirm <credential-uuid>
+neatlogs api-keys revoke <credential-uuid> --confirm <credential-uuid>
+neatlogs ingest-credentials create --name <name> [--expires-in-days 1-365]
+neatlogs ingest-credentials rotate <credential-uuid> --confirm <credential-uuid>
+neatlogs ingest-credentials revoke <credential-uuid> --confirm <credential-uuid>
+neatlogs mcp status
+neatlogs coding-tools status
+neatlogs --project <uuid> api <operationId> [--param <name=value...>] [--query <name=value...>]
+printf '%s' '{"q":"failed checkout"}' | neatlogs --project <uuid> api post_api_v1_public_search_traces --body-stdin
+neatlogs schema list
+neatlogs schema search <query>
+neatlogs schema show <operationId>
+```
+
+For confidential or multiline prompt text, prefer bounded stdin so content is
+not exposed in shell history or process arguments. Prompt content is limited to
+60 KiB within the Public API's 64 KiB JSON request ceiling:
+
+```bash
+neatlogs prompts create --name support-answer --content-stdin < prompt.txt
+neatlogs prompts create --body-stdin < complete-prompt-request.json
+```
+
+Use `--body-stdin` when messages, variables, configuration, or commit metadata
+are also sensitive. It is mutually exclusive with individual prompt field
+options and validates the complete request before sending it.
+
+Version creation and label activation are intentionally separate authorization
+steps: `prompts create` requires prompt write access, while `prompts label`
+requires prompt management access.
+
+`api` accepts only operation IDs with an explicit handler compiled into this
+CLI release. `--param` and `--query` accept bounded `name=value` pairs, reject
+duplicates, and are checked against that operation's embedded parameter
+allowlist before any request. Body-bearing safe reads accept one object from
+`--body-stdin`, bounded to 64 KiB and validated against the embedded request
+schema before any request. `schema` commands are offline and do not require credentials.
+`schema list` and `schema search` return concise descriptors. `schema show`
+returns the normalized embedded operation contract, including request and
+response schemas, authentication requirements, and execution/risk metadata.
+New schema operations default to non-executable until an explicit handler and
+risk classification are added.
+
+Raw `api` execution fails closed for operations that require target-specific
+destructive confirmation. Use the operation's curated command instead; raw
+execution intentionally has no generic `--confirm` flag because confirmation
+bindings differ by resource.
+
+Feedback and webhook bodies use bounded stdin so comments, expected responses,
+destination URLs, and write-only webhook secrets do not appear in process
+arguments. Integration status is local and redacted; it does not discover
+providers, decrypt credentials, or contact external services.
+
+Organization discovery is OAuth-only. Organization list requires
+`context:read` plus current `org:read`; detail requires `organization:read`
+plus current `org:read`. Project discovery accepts OAuth or service-account
+tokens, requires `context:read` plus current `project:read`, and sends no
+`x-project-id`. Legacy credentials and an explicitly selected project are
+rejected locally for all discovery commands.
+
+Account profile and notification-preference reads are OAuth-only and require
+`profile:read`. Profile ignores a globally configured project and never sends
+`x-project-id`; it exposes `avatarConfigured`, never an avatar URL. Notification
+preferences require `--project` or `NEATLOGS_PROJECT_ID`, bind the current user
+to that selected project, and print all channel, digest, Slack-DM, and
+quiet-hours settings. Service-account and legacy credentials are rejected
+locally before a request.
+
+Saved-filter reads are OAuth-only and require a selected project,
+`observability:read`, and current `trace:read`. Lists omit filter criteria;
+detail returns only the caller-owned, project-bound filter tree. Trees are
+bounded to 8 group levels, 100 total nodes, and 256 KiB. Opaque list cursors
+bind the operation, selected project, OAuth actor, and normalized list filters.
+
+Organization-access reads are also OAuth-only, forbid project selection, and
+require `organization:read` plus the caller's current `member:read` permission.
+Member responses expose only safe identity and active-membership fields.
+Invitation pages omit tokens and accepted invitations, default to `pending`, and
+can filter pending or expired rows. Role results are action-specific assignment
+options; ownership transfer is not exposed.
+
+Invitation mutations are OAuth-only, forbid project selection, and reuse a
+stable idempotency key for retries. Invite accepts only generated assignable
+roles. Resend and revoke bind both the organization and exact invitation UUID;
+revoke additionally requires repeating that UUID with `--confirm`. Acceptance
+reads the confidential token only from bounded non-interactive stdin via
+`--token-stdin`; the token is never accepted as an argument or option value and
+is not emitted in CLI output or diagnostics.
+
+Alert-rule reads accept OAuth users and project-bound service accounts with
+`configuration:read`, current `alert:read`, and an exact selected project.
+`alerts list` returns bounded summaries with an opaque cursor; `alerts get`
+returns typed rule configuration plus only a channel-presence mask. Neither
+command exposes destination IDs, webhook configuration, creator identity,
+tenant IDs, nor the internal property-filter DSL. Detail reports explicit
+description/condition truncation flags and the original condition count.
+`alerts history` reads a maximum 30-day fire window with an optional rule
+filter, signed cursor, five bounded sample trace IDs, delivery-kind allowlist,
+and truncation counts; it excludes private rule-change history, payloads,
+destination identifiers, project IDs, actor data, and breaching span IDs.
+`alerts changes` reads a rule's privacy-safe change audit, including after soft
+deletion. It returns only strict change types, allowlisted public field names,
+and bounded redaction counts; actor identity and raw before/after values are
+never returned.
+
+Detection read commands validate UUIDs, page bounds, status, path
+parameters, response size, and the generated response schema before emitting
+output. Their server operations accept OAuth or service-account tokens and
+require a selected project plus `configuration:read` and `detection:read`; a
+service account must also have an active binding to that project.
+Lists return compact summaries and an opaque `nextCursor` when another page is
+available. Pass that value unchanged with `--cursor`; page size may change
+between requests. `detections get` returns the typed detector
+configuration under a 768 KiB server budget and a 1 MiB client ceiling.
+`detections history` returns created/updated/toggled/deleted events with only
+the actor category and an allowlisted changed-field list. It never returns
+user IDs, email addresses, service-account IDs, or before/after diff values.
+Detection-result commands use the data-plane authorization boundary instead:
+`observability:read` plus current `trace:read`. `detections hits` returns only
+bounded trace/span references and scores, never detector metadata or trace
+payloads, and uses a signed project-and-detection-bound cursor. `detections
+trends` accepts a maximum 90-day window and returns UTC hour/day/week buckets.
+
+With the server mutation gate enabled, managed detection commands are:
+
+```bash
+neatlogs detections create --group <group-id> --name "PII" --type pii --config '{"entities":["EMAIL_ADDRESS"]}'
+neatlogs detections update <detection-id> --threshold 0.8
+neatlogs detections disable <detection-id>
+neatlogs detections enable <detection-id>
+neatlogs detections delete <detection-id> --confirm <detection-id>
+```
+
+Create/update validate bounded type-specific JSON on the server, require
+`configuration:write`, current `detection:manage`, an exact selected project,
+and an idempotency key. The CLI generates a UUID unless a retry deliberately
+reuses `--idempotency-key`. Enable/disable set the desired state rather than
+toggling, so replay is safe. Delete is non-interactive, requires the exact ID
+twice, and refuses while any live ID-bound or legacy name-bound alert rule
+depends on the detection. Configuration changes invalidate prior results and
+schedule a backfill after the transaction commits.
+
+Detection-group catalog commands are `groups list` and `groups get`. With the
+server mutation gate enabled, `groups create --name`, `groups update <id>
+--name`, and `groups delete <id> --confirm <id>` provide managed-group parity.
+Create/update/delete accept an optional `--idempotency-key`; otherwise the CLI
+generates a fresh UUID. Delete is non-interactive and requires the exact group
+ID twice, which is safe for coding agents and CI. These operations require
+`configuration:write`, current `detection:manage`, and a selected project; an
+OAuth user or project-bound service account may call them.
+
+Evaluation commands accept OAuth or service-account tokens. They require a
+selected project, `evaluation:read`, and current `eval:read`; a service account
+must also have an active binding to that project. Lists are
+compact and project-scoped; `evals get` returns the bounded evaluation
+configuration under a 512 KiB server budget and the same 1 MiB client ceiling.
+Progress uses one tenant-scoped database snapshot. Item commands expose bounded
+metadata only—not trace payloads, forms, answers, evaluator identity, or
+internal revision fields—and item pages have a 768 KiB server ceiling.
+`evals form get` returns only the current bounded question projection. With the
+mutation gate enabled, a creator can use `evals form set --body-stdin` to append
+and activate an immutable draft-form version; internal evaluator assignments
+and AI verdict keys are never exposed. Replacement is human-evaluation-only and
+returns a conflict when current questions carry private evaluator routing or AI
+verdict metadata, preventing a read/edit/write cycle from widening access.
+
+The evaluation creator can launch an existing-trace human evaluation and assign
+it to themselves:
+
+```bash
+neatlogs evals launch '<evaluation-uuid>' --assign-me --review-duration 7d
+```
+
+This OAuth-user-only action requires creator ownership and sends no email or
+Slack notification; the assignment remains available in the NeatLogs app.
+
+Assigned-review discovery and reads are OAuth-only because an assignment belongs
+to a real user. Draft and submit additionally require `evaluation:write`,
+current `eval:submit`, and `PUBLIC_API_MUTATIONS_ENABLED=true` on the server.
+The CLI reads a bounded JSON object from stdin and creates a high-entropy
+idempotency key unless `--idempotency-key` is supplied for a deliberate retry.
+If an automatically generated key reaches an ambiguous timeout, network, or
+server-contract failure, the CLI prints that non-secret UUID in its diagnostic;
+reuse it with `--idempotency-key` instead of minting a new mutation.
+The same key and same request replay the stored result; reusing a key for a
+different body fails with `IDEMPOTENCY_KEY_CONFLICT`. Service accounts cannot
+impersonate a human reviewer.
+
+Reusable evaluator definitions use `evaluators list|get|create|update|archive|
+restore|duplicate`. Reads require `evaluation:read` and current `eval:read`;
+writes require `evaluation:write`, current `eval:manage`, and the server
+mutation gate. Create/update accept bounded JSON only through `--body-stdin`,
+so prompts and tool configuration do not appear in shell history. Tool config
+is write-only and is never printed; detail output reports only whether each
+grant is configured. Archive/restore are explicit state-setting patches, and
+duplicate atomically copies the definition, hidden grant configuration, and
+pinned skills under a new non-conflicting name.
+
+Trace/session commands accept legacy registry-v2 keys, OAuth, or service-account
+tokens. OAuth/service-account credentials require a selected project; a legacy
+key uses its bound project and may omit one. All require `observability:read`
+and current `trace:read`. Search is bounded to 30 days and 16 terms; keyword and semantic
+pagination uses actor/project/query-bound opaque snapshots. Raw previews are
+byte-capped. `traces payload` requires a unique explicit field allowlist and
+never returns object-storage locations or presigned URLs.
+Search results expose at most 20 matched span identities per trace and only
+their ID, name, and type. Trace/session exports support bounded JSON, Markdown,
+and CSV. Human terminal output prints Markdown/CSV directly; `--json` preserves
+the response envelope for pipelines. Export composition uses public projections
+only and excludes raw payloads, private attributes, snippets, and S3 locations.
+
+Guest-link and trace-sharing reads accept OAuth or service-account tokens,
+require a selected project, `sharing:read`, and current `sharing:read`. They do
+not accept legacy keys. Responses expose only bounded metadata and state—never
+guest tokens, token hashes, public URLs or IDs, recipient email, creator
+identity, or tenant identifiers. `guest-links list` cursors bind the operation,
+selected project, and authenticated actor.
+
+Guest-link mint requires `--recipient-email <email>`, normalizes the recipient,
+and reveals the opaque token once. Rotation preserves the recipient and reveals
+only the replacement token; metadata reads never reread either token. Guest
+review uses no stored credential, profile, selected project, or environment
+token. The capability token and request must arrive together as strict JSON on
+stdin:
+
+```bash
+printf '%s' '{"token":"<guest-token>"}' |
+  neatlogs guest context --request-stdin
+
+printf '%s' '{"token":"<guest-token>","answers":[{"questionId":"<question-uuid>","answerValue":"yes"}]}' |
+  neatlogs guest submit '<item-uuid>' --request-stdin
+```
+
+Context accepts 1–25 items per page (default 25), at most 100 questions, 16 KiB
+UTF-8 input and output previews with truncation flags, and a 1 MiB final
+envelope. Submission accepts at most 100 distinct answers, 32 KiB per answer,
+and 64 KiB raw JSON. It performs full answer replacement, including clearing
+omitted optional answers. The CLI generates a high-entropy idempotency key
+unless the caller supplies one for an intentional retry. Expired or revoked
+tokens fail on fresh execution and replay. The generic `neatlogs api` executor
+cannot run guest operations. Browser guest routes remain compatible because
+they use the same context and submission services.
+
+Credential inventory commands accept OAuth or service-account tokens, require
+the selected project's current `api_key:read` permission plus `access:read`,
+and reject legacy keys as callers. `api-keys list` reports safe Public API key
+prefix metadata and whether the broad legacy project key is configured.
+`ingest-credentials list` reports dedicated prefix/last-four hints and, for an
+OAuth caller only, whether that caller has a legacy personal write key for the
+selected organization. Neither command can reread plaintext or verifier hashes.
+
+MCP and coding-tool status commands are OAuth-user-only, require a selected
+project and `configuration:read`, and apply current `mcp:use` or `tool:use`
+RBAC. MCP status also enforces the organization's plan entitlement. Responses
+contain only aggregate configuration/run state; they never contain stored
+tokens, URLs, headers, prompts, repositories, provider IDs, task IDs, or error
+messages. Service-account and legacy credentials are rejected locally before a
+request.
+
+## Configuration and output
+
+- `NEATLOGS_TOKEN` is the primary credential source; `NEATLOGS_API_KEY` is the
+  legacy fallback. An environment credential takes precedence over a selected
+  stored profile and is identified as `environment` by `auth status`.
+- `--profile <name>` selects non-secret host/project preferences and its
+  separately stored OAuth credential. Stored tokens are never sent when a
+  `--host` or `NEATLOGS_HOST` override differs from the credential-bound host.
+- Expiring OAuth access tokens are refreshed before an API request. Refresh
+  rotation is persisted back to the same credential store. Normal logout first
+  revokes the refresh family on the server and only then deletes the local
+  secret; `--local-only` is an explicit recovery escape hatch.
+- Product reads and selected-project context commands require `--project
+  <uuid>` or `NEATLOGS_PROJECT_ID` for OAuth/service-account credentials.
+  `--project` takes precedence. A project is optional for legacy credentials.
+  Discovery commands instead forbid any selected project.
+- A service-account token is sent only as `Authorization: Bearer` and the
+  selected project only as `x-project-id`. A legacy key is sent only as
+  `x-api-key`.
+- `--host <origin>` overrides `NEATLOGS_HOST`. One of them is required for
+  online commands; the CLI never guesses a deployment domain. Offline `schema`
+  commands require neither.
+- Hosts must be HTTPS origins with no path, user information, query, or hash.
+- Browser PKCE is the default login. `--device` is the explicit fallback for a
+  remote/headless terminal. Both request reviewed OAuth scopes; current RBAC is
+  still evaluated by the server for every API request.
+- `--json` or non-TTY stdout produces stable JSON. Data uses stdout and
+  diagnostics use stderr.
+- Requests time out after 10 seconds and never follow redirects.
+- Idempotent GET requests and explicitly marked safe POST reads retry at most
+  twice after a `429` or `503`, honoring a safe, bounded `Retry-After` value.
+- Idempotent mutating operations retry at most twice after a `429` or `503`.
+  Other mutating operations are never retried.
+
+## Guarded live-local context and organization-access smoke
+
+This developer-only smoke packs the CLI, uses the exact current worktree
+backend, exercises context discovery, saved filters, organization
+member/invitation/role reads, and all three guest-link/sharing reads, and
+creates short-lived fixtures only in the local Docker PostgreSQL database. It
+never targets staging or production.
+
+The command verifies generated API assets and rebuilds the distributable before
+packing, so the exercised binary cannot lag behind the current source/spec.
+
+Prerequisites:
+
+- the worktree backend is listening on `127.0.0.1:4100` in `development` mode,
+  with local PostgreSQL and Redis configuration;
+- local PostgreSQL is `neatlogs` on `127.0.0.1:5432` as role `neatlogs`;
+- `psql`, `openssl`, `lsof`, `git`, Node, pnpm, and npm are available; and
+- the backend listener PID and current 40-character worktree HEAD are supplied
+  explicitly. The smoke verifies the listener PID, backend working directory,
+  HEAD, and `/health` environment before fixture writes.
+
+```bash
+cd /path/to/neatlogs-app-worktree/cli
+RUN_NEATLOGS_CLI_LIVE_LOCAL=1 \
+NEATLOGS_LIVE_LOCAL_BACKEND_PID="$(lsof -nP -iTCP:4100 -sTCP:LISTEN -t)" \
+NEATLOGS_LIVE_LOCAL_EXPECTED_HEAD="$(git -C .. rev-parse HEAD)" \
+pnpm smoke:context-discovery:live-local
+```
+
+The HTTPS loopback proxy trusts only its generated loopback certificate through
+the packed CLI child's `NODE_EXTRA_CA_CERTS`; TLS verification is never
+disabled. External commands and network operations have deadlines. The smoke
+waits for every successful request's audit row to become durable, deletes only
+its exact request IDs/fixture IDs/marker, and requires zero residue. Signals
+abort active work and unwind normal cleanup, including the packed-consumer and
+certificate temporary directories.
+
+## Exit codes
+
+| Code | Meaning                                      |
+| ---: | -------------------------------------------- |
+|    0 | Success                                      |
+|    2 | Invalid arguments, configuration, or request |
+|    3 | Authentication is missing or invalid         |
+|    4 | Authorization or scope denied                |
+|    5 | Resource not found                           |
+|    6 | Conflict                                     |
+|    7 | Rate limited or temporarily unavailable      |
+|    8 | Network, TLS, timeout, or redirect failure   |
+|    9 | Partial bulk-operation success               |
+|   10 | Destructive confirmation required            |
+|   11 | Server or response-contract failure          |