NeatLogs CLI

Sign in through your browser and inspect your projects from a terminal.

An SDK project key in NEATLOGS_API_KEY sends traces and supports SDK Doctor readback; it does not authenticate public API CLI reads. If only that key is available, use Doctor and mark optional CLI readback waiting on a human until OAuth approval or a suitable service token is available.

Use the CLI to read traces, inspect detections, work with evaluations, and manage authorized project resources. People sign in with OAuth. Unattended automation can use service-account tokens; an AI host acting as a person uses the separate user OAuth MCP connection.

1. Install

Use Node.js 22 or 24. These instructions target the MIT-licensed neatlogs-cli@0.2.1 release. Check registry availability before installation. The user-MCP preview commands are documented separately in login and proxy setup; do not assume this released CLI version includes them:

npm view neatlogs-cli@0.2.1 version
npm install --global neatlogs-cli@0.2.1
neatlogs --version

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

npm view neatlogs-cli dist-tags --json

The CLI includes the expanded 285-operation reference for project lifecycle, evaluation activation, classifier jobs and historical rescoring. Some workflows depend on enabled deployment capabilities. See the workflows and their prerequisites.

2. Choose a profile and sign in

NEATLOGS_CLI_HOST='https://app.neatlogs.com'
NEATLOGS_CLI_PROFILE='neatlogs-us'
neatlogs --host "$NEATLOGS_CLI_HOST" profile list
# Use this profile only if it is unused or already belongs to this host.
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile auth login

--credential-source profile selects stored OAuth credentials while keeping the application's SDK key available in the same shell. This option requires 0.2.1. On 0.2.0, omit it and prefix each OAuth command with env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN in a POSIX shell. Other shells need the equivalent per-process environment exclusion.

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 --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile 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. Discovery must receive neither --project nor NEATLOGS_PROJECT_ID; the POSIX command below excludes the variable only for that process:

env -u NEATLOGS_PROJECT_ID neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile projects list

Set the chosen project UUID for the read commands:

NEATLOGS_CLI_PROJECT='<project-uuid>'

neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile --project "$NEATLOGS_CLI_PROJECT" whoami
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile --project "$NEATLOGS_CLI_PROJECT" projects current

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

For EU, set NEATLOGS_CLI_HOST to https://eu.app.neatlogs.com and use a separate profile such as neatlogs-eu. Keep the same host and profile for login and every read; do not rebind an authenticated profile from another dashboard. The same package serves both regions once the corresponding public API is deployed. See US and EU profiles.

4. Read project data

neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile --project "$NEATLOGS_CLI_PROJECT" traces list --limit 5
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile --project "$NEATLOGS_CLI_PROJECT" detections list --limit 5
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile --project "$NEATLOGS_CLI_PROJECT" evals list --limit 5

For a known trace:

neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile --project "$NEATLOGS_CLI_PROJECT" traces get '<trace-id>' --json
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile --project "$NEATLOGS_CLI_PROJECT" 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 --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile --project "$NEATLOGS_CLI_PROJECT" traces list --all --max-items 500 --json

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

Permissions and troubleshooting

Version 0.2.1 retains read-oriented default scopes, 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 --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile 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 --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile 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 --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile 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.

In 0.2.1, auth status verifies the credential with the public API and requires context:read; it needs no project selection. A successful status does not prove permission to read a particular project or trace. In 0.2.0, status can report authenticated: true for an SDK key that the public API rejects: use project-scoped whoami and an actual trace read as the authoritative checks. See authentication recovery.

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 --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile auth status
neatlogs --help
neatlogs traces --help
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" --credential-source profile auth logout

On this page

Ask Neatlogs AI

Answers from the docs

How can I help?

Ask anything about instrumenting, tracing, or the Neatlogs dashboard.