lf-cli 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdeceb3ae604e49a50b2c4e102e0406996505257235b7b10433f8df99c526ec6
+  data.tar.gz: 831fa990a296665a8dcfd6935ec4678c02c8671eb961a9ed0e3f106b13a95a0f
+SHA512:
+  metadata.gz: f7de2b11e739ed088c1a4681549273e8668450a951dfae52fe87bcb071d1f6def1dfbc35ec551bb056e71615e0eb5a7d636dd3ac0df9df918a008fd376bcabb7
+  data.tar.gz: a34a06e7543ada8bca0b2451525222b173fa93c5de66edcc8f1b6344725a0027c7708a56717cb17d7fd3d1821d8de9d847cc784aa948c057802407e5998eae6b

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-01-23
+
+### Added
+- Initial release of lf-cli (renamed from langfuse-cli)
+- Interactive configuration setup with browser integration
+- Traces command with list and get operations
+- Sessions command with list and show operations
+- Observations command with list and get operations
+- Scores command with list and get operations
+- Metrics command with query operation and custom aggregations
+- Support for multiple output formats (table, JSON, CSV, markdown)
+- Multi-profile configuration support
+- Automatic pagination for list operations
+- Time range filtering with ISO 8601 and natural language support
+- Sorbet Runtime type safety with T::Enum and T::Struct
+- Comprehensive help messages with valid values and examples
+- 55 passing unit tests with 100% success rate
+
+### Changed
+- Renamed project from `langfuse-cli` to `lf-cli` for trademark compliance
+- Renamed executable from `langfuse` to `lf`
+- Updated description to clarify unofficial/community status
+
+### Security
+- Configuration file created with 0600 permissions (owner read/write only)
+- API keys masked in configuration display commands
+- Connection validation before saving credentials
+
+## [Unreleased]
+
+### Planned
+- Support for filtering by metadata
+- Trace export with full observation trees
+- Watch mode for real-time trace monitoring
+- Creating/updating scores via CLI
+- Integration with other observability tools

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vicente Reig Rincón de Arellano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,399 @@
+# 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.
+
+[![Gem Version](https://badge.fury.io/rb/lf-cli.svg)](https://badge.fury.io/rb/lf-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Disclaimer
+
+**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.
+
+## Features
+
+- 🔍 **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
+
+## Installation
+
+### Install from RubyGems
+
+```bash
+gem install lf-cli
+```
+
+### Install from Source
+
+```bash
+git clone https://github.com/vicentereig/lf-cli.git
+cd lf-cli
+bundle install
+bundle exec rake install
+```
+
+### Requirements
+
+- Ruby >= 2.7.0
+- Langfuse account (cloud or self-hosted)
+
+## Quick Start
+
+### 1. Configure Credentials
+
+Run the interactive setup wizard:
+
+```bash
+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`
+
+### 2. Start Querying
+
+```bash
+# 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
+```
+
+## Usage
+
+### Configuration Commands
+
+```bash
+# 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
+```
+
+### Trace Commands
+
+```bash
+# 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
+```
+
+### Session Commands
+
+```bash
+# List all sessions
+lf sessions list
+
+# Show specific session with details
+lf sessions show session_xyz789
+```
+
+### Observation Commands
+
+```bash
+# List all observations
+lf observations list
+
+# Filter by type
+lf observations list --type generation
+
+# Filter by trace
+lf observations list --trace-id trace_abc123
+```
+
+### Score Commands
+
+```bash
+# List all scores
+lf scores list
+
+# Filter by name
+lf scores list --name quality
+
+# Get specific score
+lf scores get score_123
+```
+
+### Metrics Commands
+
+```bash
+# 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
+```
+
+### Global Options
+
+All commands support these global options:
+
+```bash
+-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
+```
+
+### Time Range Examples
+
+Supports both ISO 8601 and natural language:
+
+```bash
+# 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"
+```
+
+## Output Formats
+
+### Table (Default)
+
+```bash
+lf traces list --format table
+```
+
+Outputs a formatted ASCII table - great for terminal viewing.
+
+### JSON
+
+```bash
+lf traces list --format json
+```
+
+Perfect for piping to `jq` or other tools:
+
+```bash
+lf traces list --format json | jq '.[] | select(.name == "chat")'
+```
+
+### CSV
+
+```bash
+lf traces list --format csv --output data.csv
+```
+
+Import into spreadsheets or data analysis tools.
+
+### Markdown
+
+```bash
+lf traces list --format markdown
+```
+
+Great for documentation and reports.
+
+## Configuration
+
+### Configuration File
+
+Credentials are stored in `~/.langfuse/config.yml`:
+
+```yaml
+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.
+
+### Environment Variables
+
+You can also use environment variables:
+
+```bash
+export LANGFUSE_PUBLIC_KEY="pk_..."
+export LANGFUSE_SECRET_KEY="sk_..."
+export LANGFUSE_HOST="https://cloud.langfuse.com"
+export LANGFUSE_PROFILE="production"
+```
+
+### Priority Order
+
+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
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/vicentereig/lf-cli.git
+cd lf-cli
+bundle install
+```
+
+### Run Tests
+
+```bash
+# 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
+```
+
+### Run CLI Locally
+
+```bash
+./bin/lf help
+./bin/lf config setup
+```
+
+### Code Structure
+
+```
+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
+```
+
+## API Reference
+
+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`
+
+## Contributing
+
+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
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [Thor](https://github.com/rails/thor) CLI framework
+- Uses [Faraday](https://github.com/lostisland/faraday) for HTTP requests
+- Type safety with [Sorbet Runtime](https://sorbet.org/)
+- Inspired by the excellent [Langfuse](https://langfuse.com/) observability platform
+
+## Support
+
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/vicentereig/lf-cli/issues)
+- 💬 **Questions**: [GitHub Discussions](https://github.com/vicentereig/lf-cli/discussions)
+- 📧 **Email**: hey@vicente.services
+
+## Roadmap
+
+- [ ] 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](https://langfuse.com/).

data/bin/lf

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "langfuse_cli"
+
+begin
+  Langfuse::CLI::Main.start(ARGV)
+rescue Langfuse::CLI::Error => e
+  puts "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+  puts e.backtrace if ENV['DEBUG']
+  exit 1
+end