langfuse-cli

Interact with the Langfuse API from the command line.

Install

# Run directly
npx langfuse-cli api <resource> <action>
bunx langfuse-cli api <resource> <action>

# Or install globally
npm i -g langfuse-cli
langfuse api <resource> <action>

Configuration

Use an .env file (recommended, takes precedence):

langfuse --env .env api prompts list

You can get the values from your project settings. The .env file should contain:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com  # optional, this is the default (LANGFUSE_BASE_URL also supported)

Alternatively, export env vars or pass inline flags:

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_HOST=https://cloud.langfuse.com
langfuse api prompts list

# or inline
langfuse --public-key pk-lf-... --secret-key sk-lf-... api prompts list

Usage

# Discover all resources
langfuse api __schema

# List actions for a resource
langfuse api traces --help

# List traces
langfuse api traces list --limit 10

# Get a specific trace
langfuse api traces get <trace-id>

# JSON output (for piping/scripting)
langfuse api traces list --limit 5 --json

# Preview curl command
langfuse api traces list --limit 5 --curl

# Prompts
langfuse api prompts list
langfuse api prompts get --name my-prompt

# Datasets
langfuse api datasets list
langfuse api dataset-items list --dataset-name my-dataset

# Scores
langfuse api score-v2s get-scores --limit 20

Agent Usage

A skill file is included for teaching AI agents how to use the CLI. Print it with:

langfuse get-skill

Pipe it into an agent's context or include it in a system prompt.

API Reference

See the full Langfuse API Reference.

OpenAPI Patch Script

The bundled openapi.yml is post-processed by scripts/patch-openapi.ts to flatten discriminated unions (oneOf with allOf branches) into plain objects. This is needed because specli can only generate CLI flags from flat type: object schemas — it doesn't handle oneOf/allOf. Without the patch, endpoints like prompts create produce zero flags.

The patch runs automatically as part of bun run build. To fetch a fresh spec and patch it:

# From cloud (default)
bun run refetch-openapi

# From a custom URL (e.g. local dev server)
bun run patch-openapi -- --refetch --openapi_url http://localhost:3000/generated/api/openapi.yml

# Patch only (no fetch)
bun run patch-openapi