Langfuse CLI

Interact with the Langfuse API from the command line.

Install

# Run directly
npx @langfuse/cli api <resource> <action>
# via bun:
bunx --bun @langfuse/cli api <resource> <action>

# Or install globally
npm i -g @langfuse/cli
# via bun:
bun add --global @langfuse/cli

# then run
langfuse api <resource> <action>
langfuse --env .env api <resource> <action>

Note: the package was previously published under langfuse-cli. That package is identical to thise one and will be updated alongside until we release a new major version. We recommend using @langfuse/cli from now on.

Authentication

The CLI needs the following parameters to work:

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)

You can provide them via an .env file (takes precedence):

langfuse --env .env api prompts list

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 resources naturally
langfuse api help
langfuse api prompts help
# or
langfuse api help prompts

langfuse api prompts create help

# Machine-readable discovery
langfuse api schema --json

# Create a prompt
langfuse api prompts create --json-body '{"name":"my-prompt","type":"text","prompt":"Hello {{name}}"}'

# List observations
langfuse api observations list --limit 10
# Fetch every page of a paginated list (works for page- and cursor-based endpoints), max 1000 items
langfuse api observations list --all
langfuse api observations list --limit 100 --all --max-items 5000

# List observations for a specific trace
langfuse api observations list --trace-id <trace-id>

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

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

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

# Union request bodies (prompts, evaluators, placements) take field flags
# directly: the discriminator flag (--type) selects the variant, and the
# variant's own types and required fields apply.
langfuse api prompts create --type text --name my-prompt --prompt 'Hello {{name}}'
langfuse api prompts create --type chat --name support \
  --prompt '{"role":"system","content":"be nice"}' \
  --prompt '{"role":"user","content":"{{question}}"}'

# The lossless JSON channel remains fully equivalent
langfuse api prompts create --body-json '{"name":"my-prompt","type":"text","prompt":"Hello {{name}}"}'

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

# Scores
langfuse api scores list --limit 20

# Use an API snapshot compatible with an older self-hosted deployment
langfuse --host http://localhost:3000 --api-version 3 api traces list
langfuse --host http://localhost:3000 --api-version 3.150.0 api traces list

# Detect the server version through /api/public/health
langfuse --api-version auto api prompts list

V3 API snapshots are available on self-hosted deployments only, Langfuse Cloud only supports v4 and up.

OpenAPI tags and explicit route versions remain accepted aliases, for example scores-v3 list for the canonical scores list. Verbose OpenAPI operationId values remain available in api schema --json but are never required as CLI commands.

--body-json and --body-file provide a lossless input path for nested objects, arrays, unions, and free-form JSON. Simple request-body fields also get generated kebab-case flags (for example --object-id for the objectId field) consistent with query-parameter flags; wire names in the request are never affected.

Union bodies with a discriminator (for example prompt create's chat vs. text variants) support field flags directly: the discriminator flag selects the variant and the CLI parses and validates against that variant's schema — langfuse api help <resource> <action> shows the per-variant fields. Unions without a clean discriminator stay --body-json-only rather than guessing.

Exit codes

(Useful for agents) | Code | Meaning | |---|---| | 0 | Successful API response or local command | | 1 | Unexpected internal failure | | 2 | Invalid command or input (usage); no request sent | | 3 | Missing or invalid configuration/credentials; no request sent | | 4 | Network, DNS, TLS, or timeout failure reaching the host | | 5 | The API responded with a non-success HTTP status (response is still printed) | | 6 | Local file or bundled-contract failure |

Agent Usage

The latest Langfuse skill lives in langfuse/skills. Print the current version with:

langfuse get-skill

This fetches the latest skill from GitHub, so it stays up to date. Pipe it into an agent's context or include it in a system prompt.

API Reference

See the full Langfuse API Reference.

Contributing

The CLI is implemented in TypeScript and runs on Node.js 20+ or Bun. It has zero external runtime dependencies and never parses OpenAPI during invocation.

See MAINTENANCE.md for build, API snapshot, testing, and release workflows. The version-pinned black-box suite is documented separately in conformance/README.md.