Skip to content

docs(platform): document login --json and the cli's json error codes #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aikins01 merged 1 commit into from
Oct 30, 2026
Merged

docs(platform): document login --json and the cli's json error codes #46

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 53 additions & 3 deletions docs/platform/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Use the command line
description: Search traces, sessions, logs, and usage from a terminal, a script, or an agent's shell with the telemetry command.
lastModified: 2026-10-29
lastModified: 2026-10-30
---

The `telemetry` command reads the same data as the [MCP server](/platform/mcp-server): projects, traces, sessions, logs, usage, and captured prompts and outputs. It signs in the same way and has the same read-only access to one workspace.
Expand Down Expand Up @@ -56,6 +56,18 @@ telemetry login --finish 'http://127.0.0.1:53124/callback?code=…'

Put the address in single quotes, because it contains `&`.

From version 0.1.2, a script or agent can run `telemetry login --json` instead. It never opens a browser or waits. It prints the link to pass on to a person, then exits:

```json
{
"status": "pending",
"authorization_url": "https://telemetry.dev/api/auth/oauth2/authorize?…",
"next": "telemetry login --finish '<address>'"
}
```

After the person selects **Allow**, `telemetry login --finish '<address>' --json` finishes the sign-in and prints it, with the same fields as `telemetry status --json` and `"status": "signed_in"`.

## Choose a project

Commands that read telemetry use one project. The command picks it in this order:
Expand Down Expand Up @@ -119,7 +131,7 @@ Captured text comes from your users, models, and tools. Output for people, inclu

## Use the command line in scripts and agents

Add `--json` to any command except `login` and `logout`. The data goes to stdout, and messages and progress go to stderr, so `telemetry traces --json > traces.json` writes only data.
Add `--json` to any command for JSON output; `login` and `logout` take it from version 0.1.2. The data goes to stdout, and messages and progress go to stderr, so `telemetry traces --json > traces.json` writes only data.

`projects`, `traces`, `sessions`, `logs`, and `usage` print the result of the matching MCP tool as it is returned, with the fields described in [What an agent can read](/platform/mcp-server#what-an-agent-can-read). `trace` and `payload` read every page of the result and print it as one object, with `complete: false` when they stopped at the limit.

Expand All @@ -135,6 +147,44 @@ To check whether the command is signed in, run `telemetry status --json`. It exi
| `4` | You are not signed in, the sign-in expired, or access is denied |
| `130` | Interrupted with Ctrl-C |

### Errors

From version 0.1.1, with `--json`, an error is one line of JSON on stderr and stdout stays empty:

```json
{"error":{"code":"not_signed_in","message":"You're not signed in. Run `telemetry login` first.","hint":"telemetry login","retryable":false,"exit_code":4,"cli_version":"0.1.2"}}
```

Branch on `code`, because the wording of `message` can change. `hint` is a command to run next, when there is one. `telemetry login` needs a person at a browser, so an agent should run `telemetry login --json` and pass the link on instead. `retryable` is `true` when running the same command again may succeed. Ctrl-C exits with 130 and no JSON, and `status --json` reports a missing sign-in as data on stdout with exit code 4.

| Code | Exit | Meaning |
| --- | --- | --- |
| `invalid_arguments` | 2 | An option or argument is not valid |
| `unknown_command` | 2 | There is no command with that name |
| `project_not_found` | 2 | No project in the workspace has that name or ID |
| `invalid_cursor` | 2 | `--cursor` isn't from an earlier page of this command |
| `project_ambiguous` | 2 | Several projects have that name; pass its ID |
| `project_required` | 2 | The workspace has several projects and none was chosen |
| `no_projects` | 1 | The workspace has no projects yet |
| `not_signed_in` | 4 | No sign-in is saved for this deployment |
| `sign_in_expired` | 4 | The sign-in expired or was disconnected |
| `payloads_not_allowed` | 4 | The sign-in doesn't include reading captured prompts and outputs |
| `access_denied` | 4 | The account no longer has access to the workspace |
| `sign_in_failed` | 4 | The sign-in was cancelled, refused, or used an address from another sign-in |
| `no_pending_sign_in` | 4 | `login --finish` found no sign-in waiting to finish |
| `trace_not_found` | 1 | No trace has that ID, or it is past the project's retention |
| `span_not_found` | 1 | The trace has no span with that ID, or it is past the project's retention |
| `unreachable` | 1 | telemetry.dev could not be reached |
| `timeout` | 1 | telemetry.dev took too long to answer |
| `server_error` | 1 | telemetry.dev failed to complete the request; try again |
| `tool_error` | 1 | telemetry.dev returned another error; `message` says what it was |
| `result_too_large` | 1 | The result was too large to read; narrow it with filters or `--limit` |
| `request_failed` | 1 | The request failed for another reason |
| `failed` | 1 | The command failed for another reason |
| `internal` | 1 | An unexpected error, such as a configuration file the command couldn't read or write |

New codes may be added, and existing codes keep their meaning. Version 0.1.2 added `invalid_cursor`, `access_denied`, `trace_not_found`, `span_not_found`, and `server_error`; version 0.1.1 reports those errors as `tool_error`. `sign_in_failed` and `no_pending_sign_in` appear in JSON only from 0.1.2, when `login` takes `--json`.

## Environment variables

| Variable | Default | Purpose |
Expand All @@ -152,4 +202,4 @@ The saved sign-in holds a token that reads your workspace, and only your user ca
telemetry logout
```

`logout` revokes the sign-in at telemetry.dev and removes it from this machine. If telemetry.dev doesn't confirm the revocation, the command says so. To remove the command line's access from your account, open your user menu, select **Account**, and disconnect it under **Connected apps**, as described in [Disconnect an agent](/platform/mcp-server#disconnect-an-agent).
`logout` revokes the sign-in at telemetry.dev and removes it from this machine. If telemetry.dev doesn't confirm the revocation, the command says so. From version 0.1.2, `telemetry logout --json` prints `{"was_signed_in": true, "revoked": false}` in that case, and `revoked` is `null` when there was no sign-in. To remove the command line's access from your account, open your user menu, select **Account**, and disconnect it under **Connected apps**, as described in [Disconnect an agent](/platform/mcp-server#disconnect-an-agent).