Langfuse CLI Guide 🚀

Target: langfuse-cli (npm) Purpose: Command-line interface wrapping the Langfuse REST API for traces, prompts, datasets, and scores. Optimized for AI agents.

🚀 Quick Start

• Zero-Install Execution: Run npx langfuse-cli api <resource> <action>.
• Dynamic Discovery: Use npx langfuse-cli api __schema to discover resources dynamically rather than assuming endpoints.

🔧 Configuration

• Credentials Precedence: --host flag > LANGFUSE_BASE_URL (standard) > LANGFUSE_HOST > Default cloud URL.
• Preferred Setup: Use an .env file containing LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_BASE_URL.
• Piping Output: Append --json for jq/script parsing or --curl to preview raw requests.

💡 Best Practices & Patterns

• Agent Provisioning: Instead of hardcoding API knowledge, have agents run langfuse get-skill to fetch and inject the latest Agent Skill directly into their prompt context.
• Schema Patching: The CLI auto-flattens discriminated unions (oneOf/allOf) via patch-openapi.ts. Always run langfuse api <resource> --help to view the flattened parameter flags.
• Security: Always prefer .env over CLI flags (like --public-key) to prevent leaking credentials in bash history.

🚨 Gotchas / Warnings (Anti-patterns)

• The --version Flag Collision: Do NOT use --version to fetch specific API resource versions (e.g., prompt versions). Commander.js intercepts --version globally. Anti-pattern: langfuse api prompts get my-prompt --version 4. Pattern: Use --prompt-version 4 instead.
• Host Variable Deprecation: Do not rely solely on LANGFUSE_HOST in newer setups. Pattern: Migrate to LANGFUSE_BASE_URL as the ecosystem standard.
• Raw Union Payloads: Do not pass raw nested discriminated union JSON bodies directly; use the flattened flag structure shown in the CLI help.