NeatLogs CLI

Use the CLI to read traces, inspect detections, work with evaluations, and manage authorized project resources. People sign in with OAuth; CI and AI agents use service-account tokens.

1. Install

Use Node.js 22 or 24. Install the stable MIT-licensed release, neatlogs-cli@0.1.0:

npm install --global neatlogs-cli@0.1.0
neatlogs --version

The executable is neatlogs. You can verify the published package before installing it:

npm view neatlogs-cli@0.1.0 version

2. Save a profile and sign in

neatlogs profile set work --host 'https://app.neatlogs.com'
neatlogs profile use work
neatlogs auth login

In an interactive terminal, the CLI opens the browser for OAuth consent and prints a URL you can open manually. After you approve, return to the terminal; it stores the OAuth credentials in your operating-system vault.

In a headless terminal, the CLI selects Device Flow automatically. You can request it explicitly:

neatlogs auth login --device

Open the displayed verification URL on a device with a browser and approve the request. Never share the authorization URL, device code, or resulting credentials.

3. Select your project

List the projects your signed-in user can access:

neatlogs projects list

Save the chosen project UUID in the active profile:

neatlogs profile set work --host 'https://app.neatlogs.com' \
  --project '<project-uuid>'

neatlogs whoami
neatlogs projects current

Profiles store non-secret host and context preferences. OAuth credentials are stored separately and bound to the host and profile.

For EU, use a separate profile with https://eu.app.neatlogs.com as its host. The same package serves both regions once the corresponding public API is deployed. See US and EU profiles.

4. Read project data

neatlogs traces list --limit 5
neatlogs detections list --limit 5
neatlogs evals list --limit 5

For a known trace:

neatlogs traces get '<trace-id>' --json
neatlogs traces spans list '<trace-id>' --limit 25 --json

--json provides structured output for scripts. Cursor-list commands can collect several pages with an explicit ceiling:

neatlogs traces list --all --max-items 500 --json

For bounded analytics, pagination, and collaboration prerequisites, see tested CLI workflows.

Permissions and troubleshooting

The stable 0.1.0 release requests read-oriented scopes by default, including detection reads through configuration:read. Earlier 0.1.0-team-test.6 requested the complete CLI scope set. Current roles and entitlements still apply. Use --scope to request the permissions for a particular workflow:

neatlogs auth login \
  --scope context:read observability:read evaluation:read configuration:read offline_access

For a workflow that also writes evaluations, request its required scopes explicitly:

neatlogs auth login \
  --scope context:read observability:read evaluation:read evaluation:write offline_access

For service-account setup or managed credential creation and revocation, sign in with the access scopes those operations require. The default login does not include access:write:

neatlogs auth login \
  --scope context:read organization:read access:read access:write offline_access

These administration commands require a human OAuth identity and current permission to manage the target service account or project credential. Token scopes granted to the automation identity are separate from the OAuth scopes used to administer it.

Your current role must also allow the operation. A 403 means a scope, role, binding, or entitlement is missing; API error guidance explains other failures.

Upgrading the CLI does not change scopes already issued to stored OAuth credentials. After upgrading to the stable release, log out of the selected profile and sign in again to apply its new default scopes. Request write scopes explicitly for workflows that need them.

On Linux, OAuth credential storage requires libsecret and a running Secret Service. The CLI reports an error when the vault is unavailable. Credential storage options explain the explicit file-storage fallback for supported POSIX systems.

neatlogs auth status
neatlogs --help
neatlogs traces --help
neatlogs auth logout