Tested CLI workflows
Select the right context, supply bounded dates, and understand lifecycle requirements.
These examples target 0.2.1, pending publication; see installation. Use these commands with the host and project for your environment. For dev, use
https://dev.neatlogs.com; for the US customer app, use https://app.neatlogs.com;
for EU, use https://eu.app.neatlogs.com after public API deployment there.
Credentials issued by one region or environment cannot authorize another.
Select context before reading data
NEATLOGS_CLI_HOST='https://app.neatlogs.com'
NEATLOGS_CLI_PROFILE='neatlogs-us'
neatlogs --host "$NEATLOGS_CLI_HOST" profile list
# Choose an unused profile or one already bound to this exact host.
nl() {
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" \
--credential-source profile "$@"
}
nl auth login --device
# Continue after the user approves the displayed code in their browser.
env -u NEATLOGS_PROJECT_ID neatlogs --host "$NEATLOGS_CLI_HOST" \
--profile "$NEATLOGS_CLI_PROFILE" --credential-source profile projects list --json
NEATLOGS_CLI_PROJECT='<project-uuid>'
nl projects current --project "$NEATLOGS_CLI_PROJECT" --json
# Add explicit project context for the remaining project-scoped examples.
nl() {
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" \
--credential-source profile --project "$NEATLOGS_CLI_PROJECT" "$@"
}The nl shell helper keeps the host, OAuth profile and project consistent while ignoring SDK credential variables. On 0.2.0, remove --credential-source profile from both helper definitions and prefix their neatlogs invocation with env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN. Also replace the standalone discovery command with:
env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN -u NEATLOGS_PROJECT_ID \
neatlogs --host "$NEATLOGS_CLI_HOST" --profile "$NEATLOGS_CLI_PROFILE" projects list --jsonThese exclusions affect only the CLI process; the application keeps its SDK key. For EU, change the host and profile together before login.
projects list is an organization-level operation: omit explicit --project and NEATLOGS_PROJECT_ID for that command. A project saved in a profile can still be used by project-level commands.
Analytics requires both dates
Every analytics query requires an inclusive --from and an exclusive --to, in RFC 3339 format. The query window must be positive and no longer than 30 days. Choose a window that contains the traces you want to inspect; an empty result can be valid.
FROM='2026-09-23T00:00:00Z'
TO='2026-09-30T00:00:00Z'
nl analytics kpis --from "$FROM" --to "$TO" --json
nl analytics cost --from "$FROM" --to "$TO" --json
nl analytics chart --from "$FROM" --to "$TO" \
--granularity day --timezone UTC --json
nl analytics facets --from "$FROM" --to "$TO" \
--field workflowName --limit 20 --jsonnl analytics kpis --json alone is incomplete. An argument error is local validation and has no server request ID because it does not send an HTTP request.
Read traces and continue pagination
nl traces list --from "$FROM" --to "$TO" --limit 5 --json
nl traces list --from "$FROM" --to "$TO" \
--limit 5 --cursor '<page.nextCursor>' --json
nl traces get '<trace-id>' --json
nl traces spans list '<trace-id>' --limit 25 --json
nl traces export '<trace-id>' --format json --jsonUse the same filters and dates when continuing a cursor. A cursor is bound to its operation, actor and project; it cannot be moved between projects or environments. --all --max-items 100 gives collection an explicit ceiling.
Keyword search is a separate read path. Successful trace listing does not establish that search's index is ready. A 503 from search requires investigation of the deployment's search readiness; do not treat it as an empty search result.
Comment and evaluation prerequisites
comments create adds a message to an existing thread:
nl comments list --trace '<trace-id>' --limit 25 --json
printf '%s' 'Review note' | nl comments create \
--trace '<trace-id>' --thread '<thread-id>' --content-stdin --jsonThe Public API does not create the initial trace-comment thread. If the trace has no thread, create it in the dashboard first. Comment writes require an OAuth user with observability:write and the corresponding current role permission.
A new evaluation is a draft. The current Public API launch workflow assigns the signed-in user with assignMe: true; it does not accept a list of other reviewers. See evaluation commands for the cohort, form and launch requirements. Do not use draft creation as proof that review dispatch or completion works. Draft deletion is not available through this API.
Complete a self-review evaluation
Use a trace from the selected project and a current role that allows evaluation writes. Request write scopes explicitly when signing in with a client that defaults to read scopes:
nl auth login --scope context:read observability:read \
evaluation:read evaluation:write offline_access
TRACE_ID='<trace-id>'
EVAL_ID=$(printf '%s' '{"name":"CLI self-review","type":"human","traceSource":"existing","sendFrequency":"manual"}' | \
nl evals create --body-stdin --json | jq -r '.data.id')
printf '%s' '{"name":"Review","questions":[{"answerType":"short_answer","questionText":"Review result","isRequired":true,"sortOrder":0}]}' | \
nl evals form set "$EVAL_ID" --body-stdin --json
PREVIEW_HASH=$(jq -n --arg trace "$TRACE_ID" \
'{action:"add",references:[{kind:"trace",traceId:$trace}]}' | \
nl evals cohort preview "$EVAL_ID" --request-stdin --json | \
jq -r '.data.normalizedInputHash')
jq -n --arg trace "$TRACE_ID" --arg hash "$PREVIEW_HASH" \
'{previewHash:$hash,references:[{kind:"trace",traceId:$trace}]}' | \
nl evals cohort add "$EVAL_ID" --request-stdin --json
nl evals launch "$EVAL_ID" --assign-me --review-duration 1h --json
ITEM_ID=$(nl evals items list "$EVAL_ID" --limit 1 --json | jq -r '.data.items[0].id')
QUESTION_ID=$(nl evals form get "$EVAL_ID" --json | jq -r '.data.questions[0].questionId')
jq -n --arg question "$QUESTION_ID" \
'{answers:[{questionId:$question,answerValue:"Reviewed through the CLI"}]}' | \
nl evals review submit "$EVAL_ID" "$ITEM_ID" --body-stdin --json
nl evals progress "$EVAL_ID" --json
STATUS=$(nl evals get "$EVAL_ID" --json | jq -r '.data.status')
if [ "$STATUS" = "active" ]; then
nl evals close "$EVAL_ID" --confirm "$EVAL_ID" --json
fi
nl evals get "$EVAL_ID" --jsonThis sequence uses jq to pass IDs between commands. Confirm each result before continuing if a command fails. Submitting the last required response can complete the evaluation automatically. Read its status and close it only while it remains active; closing an already completed evaluation returns a conflict. Completion retains the evaluation and its submitted response; it does not delete the record.
Compute capabilities and release compatibility
Detection preview/generation/suggestions and analytics export require tier-c-compute. Their presence in --help or the embedded schema describes the client contract; it does not establish that the serving deployment enables the operation. Operation availability explains capability labels and 404 results.
A server response rejected with INVALID_RESPONSE is a client/server contract mismatch. Record the installed CLI version and the request ID when it is reported, then check for a CLI update. Older clients may omit the request ID when decoding fails; include the operation and approximate UTC time in that case. Do not blindly repeat a write: it may already have succeeded. Reuse the same idempotency key for recovery, and read the resource back before creating another one.
