lf-cli

An open-source CLI for Langfuse®

A powerful command-line interface for querying and analyzing Langfuse LLM observability data. Built with Ruby and designed for developers who prefer working in the terminal.

This is an unofficial, community-maintained CLI tool for Langfuse.

This project is not affiliated with, endorsed by, or sponsored by Langfuse GmbH. Langfuse® is a registered trademark of Langfuse GmbH.

• 🔍 Query Traces - List and filter traces by name, user, session, tags, or time range
• 📊 Analyze Sessions - View complete session details with all associated traces
• 🎯 Inspect Observations - List LLM generations, spans, and events
• 📈 Query Metrics - Run analytics queries with custom aggregations and dimensions
• ⭐ View Scores - Access quality scores and evaluation metrics
• 🎨 Multiple Output Formats - Table, JSON, CSV, or Markdown
• 🔐 Multi-Profile Support - Manage credentials for dev, staging, and production
• 🌐 Interactive Setup - Browser-integrated credential configuration
• ⚡ Type-Safe - Built with Sorbet Runtime for reliability

gem install lf-cli

git clone https://github.com/vicentereig/lf-cli.git
cd lf-cli
bundle install
bundle exec rake install

• Ruby >= 2.7.0
• Langfuse account (cloud or self-hosted)

Run the interactive setup wizard:

lf config setup

This will:

1. Ask for your Langfuse project name
2. Open your browser to the Langfuse settings page
3. Prompt you to enter your API keys
4. Test the connection
5. Save credentials securely to ~/.langfuse/config.yml

# List recent traces
lf traces list --from "1 hour ago" --limit 20

# Get specific trace details
lf traces get trace_abc123

# Query metrics
lf metrics query --view traces --measure count --aggregation count

# Interactive setup (recommended)
lf config setup

# Set credentials manually
lf config set production \
  --public-key pk_... \
  --secret-key sk_...

# Show current configuration (keys are masked)
lf config show

# List all profiles
lf config list

# List all traces
lf traces list

# Filter traces by various criteria
lf traces list \
  --name "chat_completion" \
  --user-id user_123 \
  --from "2024-01-01" \
  --limit 50

# Get detailed trace information
lf traces get trace_abc123

# Export to CSV
lf traces list --format csv --output traces.csv

# List all sessions
lf sessions list

# Show specific session with details
lf sessions show session_xyz789

# List all observations
lf observations list

# Filter by type
lf observations list --type generation

# Filter by trace
lf observations list --trace-id trace_abc123

# List all scores
lf scores list

# Filter by name
lf scores list --name quality

# Get specific score
lf scores get score_123

# Count total traces
lf metrics query \
  --view traces \
  --measure count \
  --aggregation count

# Average latency by trace name
lf metrics query \
  --view observations \
  --measure latency \
  --aggregation avg \
  --dimensions name

# Token usage with time range
lf metrics query \
  --view observations \
  --measure tokens \
  --aggregation sum \
  --from "2024-01-01" \
  --to "2024-12-31"

# P95 latency grouped by model
lf metrics query \
  --view observations \
  --measure latency \
  --aggregation p95 \
  --dimensions model

All commands support these global options:

-f, --format [table|json|csv|markdown]   # Output format (default: table)
-o, --output FILE                        # Save output to file
-l, --limit N                            # Limit number of results
-P, --profile PROFILE                    # Use specific profile
--from TIMESTAMP                         # Start of time range (ISO 8601 or relative)
--to TIMESTAMP                           # End of time range
-v, --verbose                            # Verbose output

Supports both ISO 8601 and natural language:

# ISO 8601
--from "2024-01-01T00:00:00Z" --to "2024-12-31T23:59:59Z"

# Natural language (requires 'chronic' gem)
--from "1 hour ago"
--from "yesterday"
--from "last monday"

lf traces list --format table

Outputs a formatted ASCII table - great for terminal viewing.

lf traces list --format json

Perfect for piping to jq or other tools:

lf traces list --format json | jq '.[] | select(.name == "chat")'

lf traces list --format csv --output data.csv

Import into spreadsheets or data analysis tools.

lf traces list --format markdown

Great for documentation and reports.

Credentials are stored in ~/.langfuse/config.yml:

profiles:
  default:
    host: https://cloud.langfuse.com
    public_key: pk_...
    secret_key: sk_...
    output_format: table
    page_limit: 50

  production:
    host: https://cloud.langfuse.com
    public_key: pk_prod_...
    secret_key: sk_prod_...

The file is created with 0600 permissions (owner read/write only) for security.

You can also use environment variables:

export LANGFUSE_PUBLIC_KEY="pk_..."
export LANGFUSE_SECRET_KEY="sk_..."
export LANGFUSE_HOST="https://cloud.langfuse.com"
export LANGFUSE_PROFILE="production"

Configuration is loaded in this order (highest to lowest priority):

1. Command-line flags (--public-key, --secret-key, etc.)
2. Environment variables (LANGFUSE_PUBLIC_KEY, etc.)
3. Config file (~/.langfuse/config.yml)
4. Defaults

This section mirrors the depth of a llms-full.txt so AI assistants can answer detailed questions about lf-cli without inspecting the source.

1. Credentials (public_key, secret_key) plus host are mandatory for all API calls.
2. Resolution order: CLI flags → environment variables → profile in ~/.langfuse/config.yml → defaults.
3. Profiles let you store multiple environments (e.g., default, staging, production) inside the same YAML file.
4. The config setup command validates keys before saving by hitting /api/public/traces with limit=1.

Environment variable matrix

Pagination strategy: the client keeps fetching pages until it collects the requested limit or no more pages remain. limit therefore caps the total combined size, not per-page size.

• table renders ASCII tables via Formatters::TableFormatter.
• json streams JSON.pretty_generate for direct piping to jq.
• csv and markdown use dedicated formatters and require array-like data (single hashes are wrapped automatically).
• --output writes the formatted string verbatim; combine with --format json for scripts.
• Use lf ... --format json | jq ... for automation recipes.

Each command inherits the global flags above. API errors exit with status code 1.

traces list options:

Sample workflow:

latest_trace_id=$(lf traces list --format json --limit 1 | jq -r '.[0].id')
lf traces get "$latest_trace_id" --format json > trace.json

Options mirror trace pagination: --from, --to, --limit, --page.

list filters:

Filters: --name, --from, --to, --limit, --page.

Single subcommand: lf metrics query.

Required flags:

Optional flags:

The CLI builds a payload matching the Langfuse metrics API (metrics array, timeDimension etc.) via Langfuse::CLI::Types::MetricsQuery.

• Trace: id, name, userId, sessionId, timestamp, durationMs, tags[], metadata (object), observations[] (optional when using get), scores[].
• Session: id, userId, name, createdAt, updatedAt, traceIds[], metadata.
• Observation: id, traceId, type (generation/span/event), name, status, model, input, output, metrics (latency, usage), level, parentObservationId.
• Score: id, name, value (number/string), type (numeric/categorical), traceId, observationId, timestamp, metadata, comment.
• Metrics response: Usually { "data": [ { "dimensions": {...}, "metrics": {...} } ], "meta": {...} }. The CLI automatically unwraps data before formatting.

Fields are passed through verbatim from the Langfuse Public API; the CLI never renames keys.

• Success exits with code 0.
• Any Langfuse::CLI::Client::*Error results in exit code 1 after printing a human-readable message.
• Specific messages:
  • Authentication Error for 401.
  • Rate limit exceeded for 429.
  • Trace/session/... not found for 404.
  • Request timed out when Faraday raises a timeout (usually after 2s).
• Use --verbose or DEBUG=1 for deeper context (e.g., stack traces, Faraday logs).

• Network issues: verify LANGFUSE_HOST by running lf config show and hitting /health with curl.
• Time parsing: install the chronic gem to enable natural language ranges; otherwise pass ISO 8601 timestamps.
• CSV exports: always provide --output file.csv to avoid large terminal dumps.
• Scripting: prefer --format json to keep machine-readable structures. Most commands return arrays, so piping to jq '.[].id' works consistently.
• Profiles: store CI credentials under LANGFUSE_PROFILE=ci and load them via lf ... -P ci to keep human/dev credentials untouched.
• Retries: built-in Faraday retry middleware already backs off (max: 3). For long-running scripts, wrap commands with shell retries instead of adding loops inside the CLI.

git clone https://github.com/vicentereig/lf-cli.git
cd lf-cli
bundle install

# Run all tests
bundle exec rspec

# Run with documentation format
bundle exec rspec --format documentation

# Run specific test file
bundle exec rspec spec/unit/commands/traces_spec.rb

./bin/lf help
./bin/lf config setup

lib/langfuse/cli/
├── client.rb           # API client with Faraday
├── config.rb           # Configuration management
├── types.rb            # Sorbet type definitions
├── formatters/         # Output formatters
│   ├── table_formatter.rb
│   ├── csv_formatter.rb
│   └── markdown_formatter.rb
└── commands/           # Command modules
    ├── traces.rb
    ├── sessions.rb
    ├── observations.rb
    ├── scores.rb
    ├── metrics.rb
    └── config.rb

This CLI uses the Langfuse Public API:

• API Documentation: https://api.reference.langfuse.com/
• OpenAPI Spec: https://cloud.langfuse.com/generated/api/openapi.yml

Valid enum values for metrics query:

• View: traces, observations, scores-numeric, scores-categorical
• Measure: count, latency, value, tokens, cost
• Aggregation: count, sum, avg, p50, p95, p99, min, max, histogram
• Granularity: minute, hour, day, week, month, auto

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Built with Thor CLI framework
• Uses Faraday for HTTP requests
• Type safety with Sorbet Runtime
• Inspired by the excellent Langfuse observability platform

• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: GitHub Discussions
• 📧 Email: hey@vicente.services

• Add support for filtering by metadata
• Implement trace export with full observation trees
• Add watch mode for real-time trace monitoring
• Support for creating/updating scores via CLI
• Integration with other observability tools

Note: This is a community project. For official Langfuse support and documentation, visit langfuse.com.