Logfire CLI Tools

Relevant source files

The following files were used as context for generating this wiki page:

• logfire/cli.py (Note: Functionality merged into logfire/_internal/cli/__init__.py as per project structure)
• logfire/_internal/cli/init.py
• logfire/_internal/cli/run.py
• logfire/_internal/config.py
• logfire/_internal/client.py
• pyproject.toml

Logfire CLI Tools provide a command-line interface for managing Pydantic Logfire projects, authentication, and application instrumentation. The CLI acts as the primary entry point for developers to authenticate with the Logfire platform, configure local project environments, and execute Python scripts with automatic OpenTelemetry instrumentation.

The tools are built using the argparse library and integrated with the rich library for formatted terminal output, including summary boxes and progress indicators during project setup.

Core Commands and Architecture

The CLI is structured into several top-level commands, each handled by specific internal modules. The entry point is defined in pyproject.toml as logfire = "logfire.cli:main".

Command Overview

Command	Function	Description
auth	parse_auth	Initiates the device authentication flow to obtain a user token.
projects	projects_subparsers	Manages project lifecycle including list, new, and use.
run	parse_run	Runs a script or module with automatic instrumentation of installed packages.
whoami	parse_whoami	Displays the current authenticated user and project configuration.
inspect	parse_inspect	Scans the environment for packages that can be instrumented but are missing.
clean	parse_clean	Deletes local Logfire data directories and credentials.

Sources: logfire/_internal/cli/init.py:228-316, pyproject.toml:79

Authentication Flow

The auth command implements a device-code authentication flow. It requests a device code from the Logfire API, directs the user to a browser for authorization, and polls the backend until a user token is returned.

Project Management

The projects command group interacts with the LogfireClient to manage cloud-based projects. It supports listing accessible projects, creating new ones, or selecting an existing project to generate a local .logfire/logfire_credentials.json file.

Credentials Structure

When a project is selected via logfire projects use or created via logfire projects new, the CLI writes a credentials file used for SDK initialization.

Field	Type	Description
token	str	The project-specific write token.
project_name	str	The human-readable name of the project.
project_url	str	The dashboard URL for the project.
logfire_api_url	str	The base URL for API requests.

Sources: logfire/_internal/config.py:1026-1035, logfire/_internal/cli/init.py:114-122

Project Selection Logic

The LogfireCredentials.use_existing_project method handles the logic for filtering and selecting projects. If multiple projects exist with the same name across different organizations, the CLI prompts the user to select the correct one using a numbered list.

Sources: logfire/_internal/config.py:1107-1168

Instrumentation and the 'Run' Command

The logfire run command allows users to execute Python code with automatic instrumentation. It uses runpy to execute modules or scripts and attempts to call logfire.instrument_<package>() for all detected compatible packages.

Instrumentation Workflow

1. Context Collection: The CLI identifies installed packages using importlib.metadata.
2. Mapping: It checks against OTEL_INSTRUMENTATION_MAP to find corresponding instrumentation wrappers (e.g., fastapi -> logfire.instrument_fastapi).
3. Execution: It configures the global Logfire instance and then runs the target script.

Recommendation System

The inspect command and the summary box in run identify "gaps" in observability. If a package like requests is installed but the opentelemetry-instrumentation-requests package is missing, the CLI provides a direct command (e.g., uv add ... or pip install ...) to install the necessary instrumentation.

Sources: logfire/_internal/cli/run.py:175-197, logfire/_internal/cli/init.py:100-111

Internal Configuration and Storage

The CLI manages two primary storage locations:

1. Global Config: ~/.logfire/default.toml stores user tokens obtained via auth.
2. Project Config: .logfire/logfire_credentials.json (within a project directory) stores the specific write token and project metadata.

Configuration Parameters

The ParamManager and LogfireConfig classes handle merging settings from environment variables, pyproject.toml files, and CLI arguments.

Parameter	Env Var	CLI Arg
Token	LOGFIRE_TOKEN	N/A
Base URL	LOGFIRE_BASE_URL	--base-url
Region	LOGFIRE_REGION	--region
Service Name	LOGFIRE_SERVICE_NAME	N/A

Sources: logfire/_internal/config.py:345-420, logfire/_internal/cli/init.py:318-325

Conclusion

Logfire CLI Tools provide a high-level abstraction over OpenTelemetry setup and project management. By automating package detection and providing a guided authentication flow, it reduces the friction of integrating observability into Python applications. Key features like the run command ensure that even legacy scripts can be instrumented without modifying source code.