@pydantic/logfire-cli-darwin-x64 0.1.4 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +115 -154
- package/bin/logfire +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,182 +1,143 @@
|
|
|
1
1
|
# Logfire CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Set up [Pydantic Logfire](https://pydantic.dev/logfire), query your telemetry,
|
|
4
|
+
and manage projects and tokens without leaving the terminal.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
at Logfire, and exposes the typed Platform API — with first-class machine output
|
|
8
|
-
for scripts and coding agents.
|
|
6
|
+
[Getting started](docs/getting-started.md) · [Install](docs/installation.md) ·
|
|
7
|
+
[User guide](docs/README.md) · [Develop the CLI](dev-docs/README.md)
|
|
9
8
|
|
|
10
|
-
##
|
|
9
|
+
## Get started
|
|
10
|
+
|
|
11
|
+
Install the native CLI with `uv`:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
uv tool install logfire-cli
|
|
15
|
+
logfire --version
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Want to try it first? Run either command without installing anything:
|
|
11
19
|
|
|
12
20
|
```bash
|
|
13
|
-
|
|
14
|
-
logfire --
|
|
15
|
-
logfire auth # browser OAuth into the OS keychain
|
|
16
|
-
logfire mcp tools list # use that session against public MCP
|
|
21
|
+
uvx logfire-cli --help
|
|
22
|
+
npx logfire-cli --help
|
|
17
23
|
```
|
|
18
24
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
| [`logfire codex`](docs/commands/codex.md) | Send Codex's own completed turns to Logfire |
|
|
31
|
-
| [`logfire token`](docs/commands/token.md) | Mint a project read/write token and print it |
|
|
32
|
-
| [`logfire api-key`](docs/commands/api-key.md) | Mint a project-scoped API key and print it |
|
|
33
|
-
| [`logfire api`](docs/commands/api.md) | Typed Platform API endpoints |
|
|
34
|
-
| [`logfire mcp`](docs/commands/mcp.md) | Discover and call the public Logfire MCP server |
|
|
35
|
-
| [`logfire doctor`](docs/commands/doctor.md) | Diagnose local prerequisites without exposing secrets |
|
|
36
|
-
|
|
37
|
-
Every command and group accepts concise `-h`/`--help`; use
|
|
38
|
-
`logfire help <command>` for the detailed option reference.
|
|
39
|
-
|
|
40
|
-
## Documentation
|
|
41
|
-
|
|
42
|
-
The [**User Guide**](docs/README.md) covers everything in task-oriented pages:
|
|
43
|
-
|
|
44
|
-
- [Installation](docs/installation.md) — the binary and shell completions
|
|
45
|
-
- [Authentication](docs/authentication.md) — logins, regions, `LOGFIRE_API_KEY`, and OS-keychain storage
|
|
46
|
-
- [Output contracts](docs/output-contracts.md) — human vs. `--output json`/`jsonl`, the envelope, exit codes, and flag precedence
|
|
47
|
-
|
|
48
|
-
Global options apply before or after every command. `--region us|eu` (env
|
|
49
|
-
`PYDANTIC_LOGFIRE_REGION`) chooses a hosted region, while `--base-url <URL>`
|
|
50
|
-
(env `LOGFIRE_BASE_URL`) targets a self-hosted or staging instance and overrides
|
|
51
|
-
it. `--org <ORGANIZATION>` selects a saved organization-specific OAuth profile;
|
|
52
|
-
`logfire auth status` lists profiles and `logfire auth switch <ORGANIZATION>`
|
|
53
|
-
changes the default without opening the credential store.
|
|
54
|
-
`--output human|json|jsonl`, `--no-input`, and `--color auto|always|never`
|
|
55
|
-
provide the shared presentation and prompting contract.
|
|
56
|
-
|
|
57
|
-
## Architecture
|
|
58
|
-
|
|
59
|
-
The CLI is a Cargo workspace of small, single-purpose crates:
|
|
60
|
-
|
|
61
|
-
| Crate | Role |
|
|
62
|
-
| --- | --- |
|
|
63
|
-
| `logfire-cli` | The `logfire` binary: argument parsing (clap) and command dispatch. |
|
|
64
|
-
| `logfire-api` | The typed `logfire api` command surface over the generated client. |
|
|
65
|
-
| `logfire-api-client` | Generated from the OpenAPI schemas (see below); never hand-edited. |
|
|
66
|
-
| `logfire-auth` | Terminal UX, organization verification, and profile persistence around browser OAuth. |
|
|
67
|
-
| `logfire-config` | Credential resolution, regions / base-URL, and the request context. |
|
|
68
|
-
| `logfire-init` | `logfire init` project setup and the `.logfire/` credentials file. |
|
|
69
|
-
| `logfire-mcp-core` | Pure, I/O-free decision core for global input/output, envelope, limit, and error-category contracts. |
|
|
70
|
-
| `logfire-mcp-client` | Official `rmcp` transport, MCP challenge and token-exchange policy, bounded protocol I/O, and protocol-faithful fakes. |
|
|
71
|
-
| `logfire-oauth` | Platform OAuth, strict SDK/HTTP policy, loopback callback, and confidential session lifecycle. |
|
|
72
|
-
|
|
73
|
-
See [`dev-docs/ARCHITECTURE.md`](dev-docs/ARCHITECTURE.md) for the product
|
|
74
|
-
boundaries and trust model, and [`dev-docs/CRATE_RULES.md`](dev-docs/CRATE_RULES.md)
|
|
75
|
-
for each crate's dependency and I/O contract. The
|
|
76
|
-
[`assurance model`](dev-docs/ASSURANCE_MODEL.md) maps critical invariants to unit,
|
|
77
|
-
property, state-machine, mutation, boundary, smoke, and end-to-end evidence.
|
|
78
|
-
|
|
79
|
-
### Design notes
|
|
80
|
-
|
|
81
|
-
- **No `unsafe`.** The workspace sets `unsafe_code = "forbid"`; safe `std`/`nix`
|
|
82
|
-
APIs have covered every need, and `forbid` (unlike `deny`) can't be overridden
|
|
83
|
-
locally.
|
|
84
|
-
- **Small release binary.** The release profile trades compile time for size
|
|
85
|
-
(`opt-level = "z"`, fat LTO, one codegen unit, `strip`, `panic = "abort"`).
|
|
86
|
-
Because `panic = "abort"` skips unwinding, the accepted trade-off is that a
|
|
87
|
-
task panic aborts the whole process without running destructors instead of
|
|
88
|
-
ending only that task.
|
|
89
|
-
- **TLS via `ring`, not `aws-lc`.** `reqwest`/`rustls` use the `ring` crypto
|
|
90
|
-
provider — much smaller, and no `cmake` at build time. Trade-off: `ring` cannot
|
|
91
|
-
verify P-521-signed certificates, so TLS can fail behind a corporate
|
|
92
|
-
TLS-inspection proxy or Cloudflare WARP that uses a P-521 CA. If you hit that,
|
|
93
|
-
the crypto provider is why; switching `reqwest` back to the default `rustls`
|
|
94
|
-
(`aws-lc`) provider fixes it.
|
|
95
|
-
- **Quality bars are enforced in CI, not by convention.** Clippy runs at
|
|
96
|
-
`-D warnings` with the `pedantic` group and `unwrap`/`expect`/`panic` denied in
|
|
97
|
-
library and binary code; `cargo-deny` gates licenses and duplicate dependencies;
|
|
98
|
-
100% line/function coverage for every handwritten crate
|
|
99
|
-
(`scripts/check_coverage.py`) and an architecture
|
|
100
|
-
policy check (`scripts/check_policy.py`) block regressions; `cargo doc` runs
|
|
101
|
-
with warnings as errors. See [`CLAUDE.md`](CLAUDE.md) for the code-style rules
|
|
102
|
-
and [`dev-docs/RUST-CONVENTIONS.md`](dev-docs/RUST-CONVENTIONS.md) for the
|
|
103
|
-
reviewed conventions.
|
|
104
|
-
|
|
105
|
-
## Generated API Client
|
|
106
|
-
|
|
107
|
-
`crates/logfire-api-client` is generated exclusively from Logfire's documented
|
|
108
|
-
Platform schema at `/api/openapi.json`. The client lives under
|
|
109
|
-
`logfire_api_client::platform`; private or compatibility schemas are not shipped.
|
|
110
|
-
|
|
111
|
-
The normalized inputs and their provenance are committed under `openapi/`. To
|
|
112
|
-
refresh the snapshot from its reviewed public HTTPS URL, inspect the schema diff,
|
|
113
|
-
and then regenerate the client:
|
|
25
|
+
You can also install it with npm:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install --global logfire-cli
|
|
29
|
+
logfire --version
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### New to Logfire?
|
|
33
|
+
|
|
34
|
+
From your application's directory, choose the organization and first project
|
|
35
|
+
names you want:
|
|
114
36
|
|
|
115
37
|
```bash
|
|
116
|
-
|
|
117
|
-
make generate-api-client
|
|
38
|
+
logfire --region us signup --org acme --project my-app
|
|
118
39
|
```
|
|
119
40
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
aliases, bounded response reads, channel discriminators, and the lint config).
|
|
129
|
-
Anything that needs to persist across a
|
|
130
|
-
regeneration belongs in that script's fix-up section.
|
|
131
|
-
|
|
132
|
-
The script requires Docker and uses OpenAPI Generator 7.22.0 through the exact OCI
|
|
133
|
-
image digest recorded in `openapi/provenance.toml`. It constructs and formats a
|
|
134
|
-
staging workspace, tests it against the exact lockfile, and only then replaces the
|
|
135
|
-
client; a final locked compile remains rollback-protected. The committed checksum
|
|
136
|
-
binds the schema snapshots, provenance, generation recipe, formatting config, and
|
|
137
|
-
complete output tree, so ordinary CI detects input or generated-client drift without
|
|
138
|
-
network access.
|
|
139
|
-
|
|
140
|
-
## Development
|
|
141
|
-
|
|
142
|
-
The hosted Logfire MCP server is the primary boundary for new remote product
|
|
143
|
-
capabilities; the documented Platform OpenAPI is the secondary typed automation
|
|
144
|
-
surface, and handwritten `/v1` calls are forbidden. See
|
|
145
|
-
[`dev-docs/ARCHITECTURE.md`](dev-docs/ARCHITECTURE.md) and
|
|
146
|
-
[`dev-docs/adr/0001-mcp-first-client.md`](dev-docs/adr/0001-mcp-first-client.md)
|
|
147
|
-
before adding a command or remote dependency, and
|
|
148
|
-
[`dev-docs/CHANGE_MAP.md`](dev-docs/CHANGE_MAP.md) for the files, tests, and docs
|
|
149
|
-
that must change together. Pure MCP command contracts live in `logfire-mcp-core`;
|
|
150
|
-
transport and OAuth stay in separate adapters.
|
|
151
|
-
|
|
152
|
-
Run the fast stable checks used by CI:
|
|
41
|
+
The CLI opens a short-lived signup page in your browser. After you approve the
|
|
42
|
+
signup, it creates the organization and project and connects the current
|
|
43
|
+
directory to that project. Use `--region eu` if your Logfire account belongs in
|
|
44
|
+
the EU region.
|
|
45
|
+
|
|
46
|
+
### Already have a Logfire account?
|
|
47
|
+
|
|
48
|
+
Sign in, then create or choose a project interactively:
|
|
153
49
|
|
|
154
50
|
```bash
|
|
155
|
-
|
|
51
|
+
logfire --region us auth --org acme
|
|
52
|
+
logfire --org acme init
|
|
156
53
|
```
|
|
157
54
|
|
|
158
|
-
|
|
55
|
+
Browser credentials stay in your operating system's credential store. `init`
|
|
56
|
+
writes the project's SDK credential to `.logfire/logfire_credentials.json` and
|
|
57
|
+
keeps it out of version control.
|
|
58
|
+
|
|
59
|
+
### Check it and do something useful
|
|
159
60
|
|
|
160
61
|
```bash
|
|
161
|
-
|
|
62
|
+
logfire --org acme project current
|
|
63
|
+
logfire --org acme wizard
|
|
64
|
+
logfire --org acme mcp query run 'SELECT message FROM records LIMIT 20' --project my-app
|
|
162
65
|
```
|
|
163
66
|
|
|
164
|
-
|
|
165
|
-
|
|
67
|
+
- `project current` verifies which Logfire project this directory uses.
|
|
68
|
+
- `project open` opens that validated project, while `--no-open` prints its URL.
|
|
69
|
+
- `wizard` prepares the account and project, then asks an installed Codex,
|
|
70
|
+
Claude Code, GitHub Copilot, Cursor, or Google Antigravity agent to instrument
|
|
71
|
+
and verify your application.
|
|
72
|
+
- `mcp query run` queries your Logfire data through the hosted MCP server.
|
|
73
|
+
|
|
74
|
+
For the complete walkthrough, including existing-project and automation flows,
|
|
75
|
+
see [Getting started](docs/getting-started.md).
|
|
76
|
+
|
|
77
|
+
## Common jobs
|
|
78
|
+
|
|
79
|
+
| I want to… | Command | Guide |
|
|
80
|
+
| --- | --- | --- |
|
|
81
|
+
| Create my Logfire account and first project | `logfire signup` | [Signup](docs/commands/signup.md) |
|
|
82
|
+
| Sign in to an existing account | `logfire auth` | [Authentication](docs/authentication.md) |
|
|
83
|
+
| Connect this directory to a project | `logfire init` | [Project setup](docs/commands/init.md) |
|
|
84
|
+
| Add application instrumentation | `logfire wizard` | [Agent-assisted setup](docs/commands/wizard.md) |
|
|
85
|
+
| Try the beta AI Gateway integration | `logfire --beta agent gateway` or `logfire --beta agent proxy launch` | [Gateway setup](docs/commands/proxy.md) |
|
|
86
|
+
| Run Python with automatic instrumentation | `logfire run` | [Run Python](docs/commands/run.md) |
|
|
87
|
+
| Query traces and logs | `logfire mcp query` | [MCP](docs/commands/mcp.md) |
|
|
88
|
+
| Open or inspect the current project | `logfire project` | [Project](docs/commands/project.md) |
|
|
89
|
+
| Create a project read or write token | `logfire token` | [Tokens](docs/commands/token.md) |
|
|
90
|
+
| Diagnose credentials or local setup | `logfire doctor` | [Doctor](docs/commands/doctor.md) |
|
|
91
|
+
|
|
92
|
+
The CLI also includes beta typed Platform API commands, safe generic MCP calls,
|
|
93
|
+
agent skills, and beta Codex telemetry setup. The [user guide](docs/README.md) lists
|
|
94
|
+
every command by task.
|
|
95
|
+
|
|
96
|
+
## Help that starts small
|
|
166
97
|
|
|
167
98
|
```bash
|
|
168
|
-
|
|
99
|
+
logfire --help
|
|
100
|
+
logfire help signup
|
|
101
|
+
logfire help init
|
|
102
|
+
logfire help mcp query
|
|
169
103
|
```
|
|
170
104
|
|
|
171
|
-
|
|
172
|
-
and
|
|
173
|
-
|
|
174
|
-
and
|
|
105
|
+
Short help keeps common choices visible. `logfire help <command>` adds examples,
|
|
106
|
+
effects, and advanced options.
|
|
107
|
+
|
|
108
|
+
For scripts and coding agents, add `--no-input` and request `--output json` or
|
|
109
|
+
`--output jsonl` instead of parsing human-readable output. See
|
|
110
|
+
[Output contracts](docs/output-contracts.md).
|
|
111
|
+
|
|
112
|
+
## Credentials stay in the right place
|
|
113
|
+
|
|
114
|
+
- Browser OAuth credentials are scoped to one Logfire origin and organization
|
|
115
|
+
and stored in the operating system credential store.
|
|
116
|
+
- Project write credentials stay with the local project under `.logfire/`.
|
|
117
|
+
- Coding agents launched by setup or bundled skills do not inherit Logfire
|
|
118
|
+
account credentials from the CLI's environment.
|
|
119
|
+
- Newly created secrets are printed once only when a token-creation command is
|
|
120
|
+
explicitly used.
|
|
121
|
+
- `--org` always means the real organization name shown in Logfire.
|
|
122
|
+
|
|
123
|
+
See [Authentication](docs/authentication.md) for multiple organizations,
|
|
124
|
+
headless API keys, logout, and credential precedence.
|
|
125
|
+
|
|
126
|
+
## Installation and updates
|
|
127
|
+
|
|
128
|
+
PyPI provides native binaries for all 17 supported targets. npm covers the five
|
|
129
|
+
common macOS, GNU/Linux, and Windows combinations. Repository readers can also
|
|
130
|
+
download every prebuilt archive, plus checksums and verification evidence, from
|
|
131
|
+
[GitHub Releases](https://github.com/pydantic/logfire-cli/releases/latest). Until
|
|
132
|
+
this repository is public, that GitHub route requires Pydantic repository access.
|
|
133
|
+
|
|
134
|
+
See [Installation](docs/installation.md) for supported platforms, one-off use,
|
|
135
|
+
updates, and shell completions.
|
|
175
136
|
|
|
176
137
|
## Contributing and security
|
|
177
138
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
[
|
|
139
|
+
Developing the CLI itself? Start with the [developer guide](dev-docs/README.md)
|
|
140
|
+
and [contribution guide](CONTRIBUTING.md). Report vulnerabilities through the
|
|
141
|
+
private process in [SECURITY.md](SECURITY.md), never through a public issue.
|
|
181
142
|
|
|
182
|
-
|
|
143
|
+
Logfire CLI is released under the [MIT License](LICENSE).
|
package/bin/logfire
CHANGED
|
Binary file
|
package/package.json
CHANGED