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 --jsonA 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 variable | Purpose |
|---|---|
NEATLOGS_HOST | App origin for requests |
NEATLOGS_PROJECT_ID | Selected project UUID |
NEATLOGS_TOKEN | Service-account or supported access token |
NEATLOGS_API_KEY | Legacy 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 10Sign 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 logoutLogout 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.
| Result | Next step |
|---|---|
MISSING_HOST | Pass --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 reads | Run projects list without --project or NEATLOGS_PROJECT_ID, then pass the selected UUID with --project. |
UNAUTHORIZED / 401 with an SDK key | Use OAuth or a scoped service-account token. An SDK project key is for ingestion and SDK Doctor, not public API reads. |
| Profile/host mismatch | Select 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 get | Check 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 | sourceUse 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
| Option | Purpose |
|---|---|
--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 |
--json | Emit structured JSON |
--jsonl | Emit one collection item per JSON line |
--fields <paths> | Select up to 32 comma-separated output field paths |
--debug | Write redacted request diagnostics to stderr |
--no-color | Disable 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 5Exit codes
| Code | Meaning |
|---|---|
0 | Success |
2 | Usage or input validation error |
3 | Authentication or credential-storage error |
4 | Authorization denied |
5 | Resource or operation not found |
6 | Conflict |
7 | Rate limited or unavailable |
8 | Network failure |
9 | Partial bulk result |
10 | Required destructive confirmation missing or invalid |
11 | Server 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.
