Skip to content
Docs Pydantic Docs

CLI

The logfire package exposes a Node-only CLI:

Terminal
npx logfire --help

Supported commands:

  • auth: authenticate with Logfire and write user credentials to ~/.logfire/default.toml.
  • auth logout: remove user credentials.
  • projects list: list projects where the current user can create write tokens.
  • projects new [project-name]: create a project and write local project credentials.
  • projects use [project-name]: create a write token for an existing project and write local project credentials.
  • projects status: show what telemetry has actually reached the project this directory is linked to.
  • read-tokens --project <org>/<project> create: create a read token and print it to stdout.
  • read-tokens create --save: create a read token and store it in the data directory instead of printing it.
  • whoami: show configured user and project information.
  • clean: remove local project credentials.
  • info: print SDK and runtime information.

The JavaScript CLI does not implement Python SDK commands such as run, inspect, gateway, or prompt.

Global options

  • --version: print the CLI, Node.js, and platform versions, then exit.
  • --region <region>: select a Logfire data region (us or eu).
  • --base-url <url>: target a self-hosted or custom Logfire API. Mutually exclusive with --region.

Auth

Authenticate once per machine:

Terminal
npx logfire auth

Use --region or --base-url to select a specific Logfire API:

Terminal
npx logfire --region us auth
npx logfire --base-url https://logfire-us.pydantic.dev auth

User auth tokens are stored in ~/.logfire/default.toml, using the same token section shape as the Python SDK.

Log out to remove stored user tokens:

Terminal
npx logfire auth logout

By default this removes every stored user token. Pass --region or --base-url to log out from only one Logfire API:

Terminal
npx logfire --region eu auth logout

Projects

Configure the current Node.js project to use an existing Logfire project:

Terminal
npx logfire projects use my-project

Or create a new project:

Terminal
npx logfire projects new my-project

Both commands write .logfire/logfire_credentials.json and .logfire/.gitignore. The Node.js runtime package reads those local credentials when no explicit token and no LOGFIRE_TOKEN are set.

Pass --data-dir <dir> to write credentials somewhere other than .logfire.

Status

To see what telemetry has actually reached the project this directory is linked to, run:

Terminal
npx logfire projects status

Project  my-org/orders
         https://logfire-us.pydantic.dev/my-org/orders

 Service         | Records | Last seen
-----------------|---------|---------------------------------
 orders-web      | 87      | 2026-08-19T01:01:29.717170+00:00
 orders-worker   | 84      | 2026-08-19T01:01:29.716577+00:00

One row per service, so a partly-instrumented system shows up as one: if you instrumented a web app and a worker but only the web app appears, the worker is not reporting.

This needs a saved read token — see below — and reports the last hour. Add --json for machine-readable output.

Read tokens

To create a read token for a project and print it to stdout, run:

Terminal
npx logfire read-tokens --project <org>/<project> create

Saving a token instead of printing it

To store the token in the data directory rather than printing it, use --save:

Terminal
npx logfire read-tokens create --save

With no --project, this uses the project the current directory is linked to. The token is written to .logfire/read_token.json, readable only by you, in the same gitignored directory that already holds your write credentials — and it is never printed, so it cannot end up in your terminal history, a CI log, or a coding agent’s transcript.

npx logfire projects status uses this token. A saved token expires after 30 days; run the command again to replace it.

A read token can read everything in the project, which may include personal data captured in span attributes. Keep .logfire/ out of version control — the CLI adds a .gitignore for you — and use npx logfire clean to remove stored credentials.

Whoami and clean

Show the configured user and project for the current directory:

Terminal
npx logfire whoami

Remove the local project credentials written by projects use/new, and any saved read token:

Terminal
npx logfire clean

Both commands accept --data-dir <dir> to read or remove credentials from a directory other than .logfire. whoami resolves project information from LOGFIRE_TOKEN, then global user auth, then local credentials, matching the Node.js runtime precedence.

Browser Safety

Local credential files are Node-only. Browser code must not receive a Logfire write token; configure @pydantic/logfire-browser with a backend traceUrl proxy instead.