Metadata-Version: 2.4
Name: logfire-cli
Version: 0.1.7
Summary: The command-line interface for Pydantic Logfire.
Home-page: https://pydantic.dev/logfire
Project-URL: Documentation, https://pydantic.dev/docs/logfire/
Project-URL: Source, https://github.com/pydantic/logfire-cli
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8

# Logfire CLI

The Rust command-line interface for [Pydantic Logfire](https://pydantic.dev/logfire).
Sign in, query your traces and logs, manage projects and tokens, and connect your
coding agent to Logfire from the terminal.

This package installs the native CLI, not the Python instrumentation SDK.
Install an application SDK separately to send telemetry; see the
[Logfire documentation](https://pydantic.dev/docs/logfire/).

## Install

Try it with [uv](https://docs.astral.sh/uv/):

```bash
uvx logfire-cli --help
```

Install it as an isolated command-line tool:

```bash
uv tool install logfire-cli
logfire --help
```

Or use `pipx install logfire-cli`. In an activated virtual environment, you can
also run `python -m pip install logfire-cli`.

The package provides both `logfire` and `logfire-cli`. If another package already
provides a `logfire` command, use `logfire-cli` or `uvx logfire-cli` to select this
CLI explicitly.

Python 3.9 or newer is required for the launcher. Wheels include the matching
prebuilt binary for macOS (ARM64 and x86-64), Windows (ARM64, x86, and x86-64),
GNU/Linux (ARM64, ARMv7, x86, x86-64, PowerPC 64 LE, RISC-V 64, and IBM Z), and
musl Linux (ARM64, ARMv6, ARMv7, x86, and x86-64). You do not need Rust installed.
GNU/Linux requires glibc 2.17 or newer, except RISC-V 64, which requires glibc
2.31. The musl wheels support compatible Alpine Linux versions.

## New to Logfire

From your application's directory, create an account, organization, and first
project in one guided flow:

```bash
logfire --region us signup --org acme --project my-app
logfire --org acme project current
```

Replace `acme` and `my-app` with the real names you want. Use `--region eu` for
the EU region. Browser OAuth credentials go to the operating system credential
store; the project SDK credential stays under `.logfire/` in your application.

Then add instrumentation with an installed coding agent:

```bash
logfire --org acme setup
```

## Use an existing account

Use your real organization name in place of `acme`, and `eu` instead of `us` if
your data is in the EU region:

```bash
logfire --region us --org acme auth
logfire --org acme mcp projects
```

Complete sign-in and approve access in your browser. OAuth credentials are stored
in the OS credential store, scoped to the Logfire origin and organization.

Choose a project from the list, then query its data through the hosted Model
Context Protocol (MCP) server:

```bash
logfire --org acme mcp query run 'SELECT message FROM records LIMIT 20' --project my-app
```

For scripts, make the target explicit and request non-interactive JSON output:

```bash
logfire --org acme --no-input --output json mcp projects
```

## Connect a local project

From your application's directory, create or choose a project interactively:

```bash
logfire --org acme init
```

To connect an exact existing project without a picker:

```bash
logfire --org acme init use --name my-app --permission send
logfire project current
```

OAuth remains in the OS credential store; the SDK token stays with the local
project. Keep credential files out of version control.

To create additional read or write tokens for that project:

```bash
logfire --org acme token read
logfire --org acme token write
```

Each command creates a new token and prints the secret once to standard output.
Store it securely; do not paste it into logs, issues, or chat. These commands do
not replace the project's saved SDK write token.

## Run Python with automatic instrumentation

The CLI selects the active project interpreter and delegates instrumentation to
the Logfire Python SDK installed in that environment:

```bash
logfire run app.py
logfire run -m uvicorn main:app
logfire run pytest tests/
```

Use `--python .venv/bin/python` when interpreter discovery is ambiguous. Run
`logfire help run` for selection rules and passthrough behavior.

## Set up instrumentation with a coding agent

With a supported coding agent installed, run this from your application's directory:

```bash
logfire --region us --org acme setup
```

The CLI detects installed agents and hands off the Logfire setup instructions
bundled with this release. The agent can change your project to add
instrumentation, using its normal permission and approval controls.
It receives the selected target and project identity, but it does not inherit
the CLI's `LOGFIRE_API_KEY`, `LOGFIRE_TOKEN`, or `LOGFIRE_MCP_TOKEN`.

If you already know the exact project and setup task, pass them explicitly:

```bash
logfire --region us --org acme setup --project api --task instrumentation
```

Use bare `setup` when you want the CLI and agent to discover the task from the
current directory.

To inspect the instructions without launching an agent:

```bash
logfire --region us --org acme wizard --print-prompt
```

## Help and updates

```bash
logfire help
logfire help mcp
logfire help wizard
uv tool upgrade logfire-cli
```

Use the upgrade command for a `uv tool install` installation; otherwise upgrade
with the package manager you used to install it.

See the [Logfire documentation](https://pydantic.dev/docs/logfire/) for application
instrumentation and platform guides. Logfire CLI is licensed under the MIT license.
