Profiles, credentials, and output

Configure the CLI and make terminal workflows predictable.

Profiles and context

neatlogs profile list
neatlogs profile show work
neatlogs profile use work
neatlogs --host 'https://app.neatlogs.com' --profile work \
  --credential-source profile --project '<project-uuid>' whoami --json

A profile stores its host and optional organization and project UUIDs. Supply an origin such as https://app.neatlogs.com, without an API path, query string, or credentials.

Explicit host and project flags take precedence over environment values, which take precedence over saved profile context. --profile selects the saved profile. With the default --credential-source auto, environment credentials take precedence over saved OAuth credentials. In 0.2.1, select --credential-source profile for human OAuth or --credential-source token for a service token. Keep the SDK project key in the application environment. Version 0.2.1 is pending publication; see the CLI install instructions.

Environment variablePurpose
NEATLOGS_HOSTApp origin for requests
NEATLOGS_PROJECT_IDSelected project UUID
NEATLOGS_TOKENService-account or supported access token
NEATLOGS_API_KEYLegacy public API credential fallback; an SDK project key is not a CLI credential

US and EU profiles

Inspect neatlogs profile list first and use each example name only if it is unused or already belongs to that exact host. Do not rebind an authenticated profile to a different dashboard.

Use the dashboard origin as the CLI host. The EU SDK ingest/backend URL https://eu.ingest.neatlogs.com is not the CLI host.

neatlogs profile set us --host 'https://app.neatlogs.com'
neatlogs profile set eu --host 'https://eu.app.neatlogs.com'
neatlogs --host 'https://eu.app.neatlogs.com' --profile eu --credential-source profile auth login --device
env -u NEATLOGS_PROJECT_ID neatlogs --host 'https://eu.app.neatlogs.com' --profile eu --credential-source profile projects list
neatlogs profile set eu --host 'https://eu.app.neatlogs.com' \
  --project '<eu-project-uuid>'
neatlogs --host 'https://eu.app.neatlogs.com' --profile eu --credential-source profile --project '<eu-project-uuid>' traces list --limit 10

Sign in separately for each profile. US credentials cannot authorize EU requests or vice versa. Region configuration in the CLI does not deploy or enable that region's API; the EU frontend/backend, schema, signing keys and desired capabilities must be deployed before these commands can work.

Credential storage

Human OAuth credentials are stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service. Linux needs libsecret and an active Secret Service implementation. Credentials are bound to the exact host, issuer, and profile.

If the native vault is unavailable on a POSIX system, auth login --allow-file-credentials explicitly permits protected plaintext storage with directory mode 0700 and file mode 0600. The CLI warns when this storage is used. Windows does not support this option. Prefer the native vault for human login and a secret store for unattended use.

neatlogs --host 'https://app.neatlogs.com' --profile work --credential-source profile auth status
neatlogs --host 'https://app.neatlogs.com' --profile work auth logout

Logout normally revokes server credentials and removes local credentials. --local-only removes only the local copy. Authenticated profiles must be logged out before deletion.

Authentication verification and recovery

In 0.2.1, auth status makes an online public API check, requires context:read, and does not require a project UUID. An authentication rejection reports authenticated: false; network, scope, or server failures remain errors. Successful status confirms authentication, not every project permission. Verify the selected project with whoami, then read the intended trace.

Version 0.2.0 only checks for a local credential and can report authenticated: true for an SDK key that later receives a 401. It also lacks --credential-source. On POSIX shells, omit that option and prefix each OAuth command with env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN; for service-token commands, exclude only NEATLOGS_API_KEY. This preserves the application's key. Use equivalent per-process environment isolation in other shells.

ResultNext step
MISSING_HOSTPass --host https://app.neatlogs.com for US or --host https://eu.app.neatlogs.com for EU, or configure that origin in the profile. Do not rely on a cloud-host default.
MISSING_PROJECT_ID on whoami or trace readsRun projects list without --project or NEATLOGS_PROJECT_ID, then pass the selected UUID with --project.
UNAUTHORIZED / 401 with an SDK keyUse OAuth or a scoped service-account token. An SDK project key is for ingestion and SDK Doctor, not public API reads.
Profile/host mismatchSelect a profile for that exact dashboard or a new unused name, then sign in there. Keep host/profile consistent on subsequent reads.
NOT_FOUND from traces getCheck the trace ID and selected project. Use the plural traces get command.

With only a project key, use SDK Doctor for controlled ingestion/readback and report CLI readback as waiting on a human. Verify the application's own trace separately from the synthetic probe.

Completion and help

Regenerate completion after updating the CLI:

# Bash
source <(neatlogs completion bash)

# zsh
source <(neatlogs completion zsh)

# fish
neatlogs completion fish | source

Use neatlogs --help, a command group's --help, or the complete command reference to discover options. neatlogs schema inspects the contract embedded in the installed release; it does not report active deployment capabilities.

Global output options

OptionPurpose
--host <origin>Override the configured app origin
--profile <name>Select a named local profile
--credential-source <source>Select environment-first resolution, stored OAuth only, or NEATLOGS_TOKEN only (0.2.1)
--project <uuid>Override the selected project
--jsonEmit structured JSON
--jsonlEmit one collection item per JSON line
--fields <paths>Select up to 32 comma-separated output field paths
--debugWrite redacted request diagnostics to stderr
--no-colorDisable terminal colors

--json and --jsonl cannot be combined. Put global output options before the command; command-specific options are listed in the reference.

neatlogs --json --fields 'traceId,traceName' traces list --limit 5

Exit codes

CodeMeaning
0Success
2Usage or input validation error
3Authentication or credential-storage error
4Authorization denied
5Resource or operation not found
6Conflict
7Rate limited or unavailable
8Network failure
9Partial bulk result
10Required destructive confirmation missing or invalid
11Server or response-contract error

Use --json for structured output. When reporting a failure, include the sanitized command, CLI and Node versions, timestamp, host, and request ID. Keep credentials and sensitive payloads out of the report.

On this page

Ask Neatlogs AI

Answers from the docs

How can I help?

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