neatlogs-cli 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,7 +2,15 @@
 
 All notable changes to `neatlogs-cli` are documented in this file.
 
-## Unreleased
+## 0.2.1
+
+- Verify `auth status` against the Public API instead of treating a configured
+  credential as authenticated; return exit 3 for rejected or missing credentials.
+- Add explicit `--credential-source profile|token|auto` selection so SDK keys
+  can coexist with stored OAuth or service-account credentials. Automatic
+  precedence, conflict rejection, and host binding remain unchanged.
+- Explain host selection, project discovery and credential recovery in JSON
+  and terminal diagnostics; update the onboarding and installation guidance.
 
 ## 0.2.0
 

package/README.md

@@ -34,20 +34,18 @@ flowchart LR
 
 ## Human quickstart
 
-The stable release candidate in this checkout is `neatlogs-cli@0.1.0`, under
-the MIT license in [LICENSE](LICENSE). It is not published by a source change.
-Verify `npm view neatlogs-cli@0.1.0 version` before using the stable install
-command; the currently published team-test release remains available through
-`npm install --global neatlogs-cli@team-test` until the reviewed release ships.
+This checkout prepares `neatlogs-cli@0.2.1`, under the MIT license in
+[LICENSE](LICENSE). Release changes are described in [CHANGELOG.md](CHANGELOG.md).
+Publication is a separate release step; check `npm view neatlogs-cli version`
+for the current stable release.
 
 1. Install the CLI and confirm that it runs.
 
    ```bash
-   npm install --global neatlogs-cli@0.1.0
+   npm install --global neatlogs-cli
    neatlogs --version
    ```
 
-   The stable candidate is `0.1.0`; publication must be independently verified.
    Use Node.js 22 or
    24. The complete dev setup and verification flow is in the
    [team quickstart](../backend/docs/public-api/dev-team-quickstart.md).
@@ -55,34 +53,57 @@ command; the currently published team-test release remains available through
 2. Save the host, select the profile, and sign in.
 
    ```bash
-   neatlogs profile set work --host '<https-app-origin>'
+   neatlogs profile set work --host 'https://app.neatlogs.com'
    neatlogs profile use work
-   neatlogs auth login
+   neatlogs --host https://app.neatlogs.com --profile work auth login --device
    ```
 
-   An interactive terminal opens browser OAuth and prints the URL as a
-   copy/paste fallback. A non-interactive or headless terminal automatically
-   uses Device Flow; `--device` selects it explicitly.
+   Approve the displayed code in your browser. Omit `--device` for browser
+   OAuth on an interactive terminal; headless terminals use Device Flow.
 
 3. List the projects you can access.
 
    ```bash
-   neatlogs projects list
+   env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN -u NEATLOGS_PROJECT_ID 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>'
+   neatlogs profile set work --host 'https://app.neatlogs.com' --project '<project-uuid>'
    ```
 
 5. Check your identity and read recent traces.
 
    ```bash
-   neatlogs whoami
-   neatlogs traces list --limit 10
+   env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN neatlogs --profile work whoami
+   env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN neatlogs --profile work traces list --limit 10
+   env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN neatlogs --profile work traces get <trace-id>
    ```
 
+The read commands use POSIX `env -u` to exclude SDK credentials only from the
+CLI process, keeping them available to the application. In other shells, use
+an equivalent clean credential environment. These examples work with the
+published 0.2.0 package.
+
+These examples use the US dashboard host; use `https://eu.app.neatlogs.com`
+for EU. `projects list` must run without `--project` or `NEATLOGS_PROJECT_ID`.
+A saved profile's project is automatically omitted for discovery.
+
+`--credential-source profile` (available in 0.2.1) ignores both credential environment
+variables and uses the selected or active profile's stored OAuth login. This
+lets an SDK application keep its `NEATLOGS_API_KEY` in the same shell. With the
+published 0.2.0 CLI, omit this new option and run each OAuth CLI command through
+`env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN` on POSIX shells, or use an equivalent
+clean credential environment on other platforms. Do not remove the SDK key
+from the application's configuration.
+
+A key-only user can verify SDK ingestion/readback with the SDK's documented
+`doctor --local` and `doctor --probe` commands without CLI login. Report CLI
+readback as **waiting on a human** unless OAuth approval or a suitable service
+account is available. A synthetic probe proves the telemetry pipeline; verify
+the application's actual trace separately.
+
 `profile set` stores non-secret host and project preferences. Login stores the
 OAuth credentials separately in the native operating-system vault.
 
@@ -587,8 +608,26 @@ 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`.
+  legacy public API key fallback, not an SDK project key. In the default
+  `--credential-source auto` mode, environment credentials take precedence over
+  a selected stored profile and differing token/key values fail closed.
+- `--credential-source profile` explicitly ignores both credential environment
+  variables and uses the saved login, including its host/project defaults.
+  Host overrides must still match the credential-bound host.
+- `--credential-source token` reads only `NEATLOGS_TOKEN`, ignoring the SDK's
+  `NEATLOGS_API_KEY`. A missing or invalid token fails without falling back to
+  another identity. Use this for service-account automation sharing an SDK shell.
+- `auth status` now verifies access against the public API. OAuth and service
+  tokens use project discovery (`context:read`); legacy public API keys use
+  their bound `whoami` context. No selected project is needed. Rejected/missing
+  credentials report `authenticated: false` and exit 3. Scope failures and
+  network failures retain their distinct errors instead of claiming the user
+  is signed out. Success reports `verification: "public_api"`; this does not
+  guarantee permission to read every project's traces.
+  Older published clients only checked local credential presence, so use
+  project-scoped `whoami` and a trace read when validating those versions.
+- Authentication and configuration diagnostics include a static, secret-free
+  `hint` in JSON and human output with the recovery steps.
 - `--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.