CI and agent automation
Run the CLI with a scoped service-account token from your secret store.
Create a dedicated service account, bind the required projects with the minimum role, and mint an expiring token with the scopes your commands need. The API quickstart shows how to create this identity in Settings → Organization → Service accounts.
These examples target 0.2.1, pending publication; see installation and release status. An SDK project key cannot authenticate public API reads. With only that key, use SDK Doctor for controlled readback and mark CLI readback waiting on a human. A service token needs context:read for identity/discovery and observability:read for traces, plus access to the selected project.
Inject NEATLOGS_TOKEN through your CI or agent secret store. Set the app origin and a bound project UUID:
export NEATLOGS_HOST='https://app.neatlogs.com'
export NEATLOGS_PROJECT_ID='<project-uuid>'
# NEATLOGS_TOKEN is supplied by the CI or agent secret store.
neatlogs --host "$NEATLOGS_HOST" --credential-source token --project "$NEATLOGS_PROJECT_ID" whoami --json
neatlogs --host "$NEATLOGS_HOST" --credential-source token --project "$NEATLOGS_PROJECT_ID" projects current --json
neatlogs --host "$NEATLOGS_HOST" --credential-source token --project "$NEATLOGS_PROJECT_ID" traces list --limit 5 --json--credential-source token reads only NEATLOGS_TOKEN, ignoring the SDK key and stored OAuth credentials. Credentials are never written to the OAuth vault. With the default auto source, NEATLOGS_API_KEY is a legacy public API credential fallback; if both credential variables are set, they must match. An SDK project key is not a legacy public API credential.
For 0.2.0, omit --credential-source token and prefix each command with env -u NEATLOGS_API_KEY on POSIX, or use equivalent per-process environment isolation. Keep the SDK key available to the application.
If the project UUID is unknown, discover accessible projects without passing a project flag or environment value:
env -u NEATLOGS_PROJECT_ID neatlogs --host "$NEATLOGS_HOST" --credential-source token projects list --jsonConfirm the UUID before setting NEATLOGS_PROJECT_ID and running project-scoped reads. A successful whoami followed by reading the intended trace verifies access; the 0.2.0 auth status result alone does not.
Bound the work
Use explicit page sizes and collection limits. The supported cursor-list commands require both --all and --max-items to collect several pages:
neatlogs --host "$NEATLOGS_HOST" --credential-source token --project "$NEATLOGS_PROJECT_ID" traces list --all --max-items 500 --jsonInspect the command reference for required confirmations, request-body input, and idempotency options before scripting writes. Handle exit codes and rate-limit delays explicitly.
Keep credentials scoped
Grant only the required token scopes and project bindings. Changing NEATLOGS_PROJECT_ID does not authorize an unbound project. Some operations require a human OAuth identity; their endpoint reference lists accepted credential types.
Rotate expiring tokens through your secret store and revoke them when the automation no longer needs access. Keep tokens and one-time secret responses out of job logs, artifacts, command arguments, and source control.
