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
7	Invalid or inconsistent API response

Langfuse-hosted skills

Install skills from Langfuse by name, label, version, tag, or all at once:

langfuse skills install skill_name
langfuse skills install skill_name@staging
langfuse skills install skill_name@3
langfuse skills install --tag tag
langfuse skills install --all
langfuse skills update

Skills commands reject API manifests that do not match the requested version or label (exit code 7). --force does not bypass this validation.

Publish a skill maintained in your repository:

langfuse skills push ./path/to/skills/skill_name --dry-run --json
langfuse skills push ./path/to/skills/skill_name \
  --commit-message "commit message"
langfuse skills push ./path/to/skills/skill_name --label production

Push includes tracked files and non-ignored untracked files in Git checkouts, and skips .git and .gitignore metadata. Git must be installed and able to read the checkout; inspection failures stop the push. Outside Git, all supported files are included by default.

Use repeatable --exclude <path> to omit specific files or directories, including outside Git. Paths are literal (no globs) and relative to each skill directory. Excluding the required root SKILL.md makes a skill invalid.

langfuse skills push ./path/to/skills/skill_name \
  --exclude credentials.json --exclude private/ --dry-run --json

Dry runs list included paths and excluded paths with reasons (gitignore, exclude, or git-metadata). Excluded directories are listed once and are not traversed. Tracked files remain eligible even if an ignore rule matches them; review the file list before publishing. Exclusions only affect new versions, so credentials exposed in older versions still need rotation.

Push all skills under a directory with opt-in recursive discovery:

langfuse skills push ./path/to/skills --recursive
langfuse skills push ./path/to/skills --recursive --update-only --dry-run --json

langfuse skills push ./path/to/skills --recursive --no-lockfile

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. CI stages releases on npm; a maintainer approves them with 2FA before they become public. The version-pinned black-box suite is documented separately in conformance/README.md.

License

MIT, see LICENSE. All third party components incorporated into the Langfuse CLI are licensed under the original license provided by the owner of the applicable component.