Skip to content

About

Interact with the full Langfuse API from the command line. Built for AI agents and power users.

Topics

Resources

Stars

71 stars

Watchers

0 watching

Forks

Repository files navigation

hero-b

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 this one and will be updated alongside until we release a new major version. We recommend using @langfuse/cli from now on.

The package name is @langfuse/cli; its installed executable is langfuse. Help prints langfuse api <resource> <action> [options]. When using a package runner, replace langfuse with npx @langfuse/cli or bunx --bun @langfuse/cli; keep the api subcommand and remaining arguments.

Authentication

Create a project API key pair under Project settings → API Keys. Put these values in .env, using the deployment where that project lives:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com
Deployment Host
EU Cloud (default) https://cloud.langfuse.com
US Cloud https://us.cloud.langfuse.com
Japan Cloud https://jp.cloud.langfuse.com
HIPAA US Cloud https://hipaa.cloud.langfuse.com
Self-hosted Your deployment URL, e.g. http://localhost:3000

Use the deployment base URL, without /api/public or a project page path. Load the file explicitly; the CLI does not automatically read .env:

langfuse --env .env api prompts list
# Without a global installation:
bunx --bun @langfuse/cli --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 --host https://us.cloud.langfuse.com --public-key pk-lf-... --secret-key sk-lf-... api prompts list

Flags override configuration. Values from --env override shell variables with the same name. Host selection then uses LANGFUSE_BASE_URL, LANGFUSE_HOST, or the EU default, in that order. Set either host variable; if both are present, LANGFUSE_BASE_URL wins. No separate login step is needed.

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 --body-json '{"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.

Create scores

The current API accepts an array of scores, including for a single score. Replace TRACE_ID with an existing trace ID:

langfuse --env .env api scores create --body-json \
  '[{"traceId":"TRACE_ID","name":"quality","value":0.9,"dataType":"NUMERIC"}]'

# Boolean values are numbers (0 or 1); categorical values are strings.
langfuse --env .env api scores create --body-json \
  '[{"traceId":"TRACE_ID","name":"helpful","value":1,"dataType":"BOOLEAN"},{"traceId":"TRACE_ID","name":"sentiment","value":"positive","dataType":"CATEGORICAL"}]'

# Or save the same JSON array in scores.json.
langfuse --env .env api scores create --body-file scores.json

To score an observation, include "observationId":"OBSERVATION_ID" alongside traceId in each JSON object. Score creation uses --body-json or --body-file; individual body field flags are unsupported. Add --curl to preview a request without sending it.

HTTP 202 means the batch was accepted for asynchronous processing. For HTTP 207, inspect the accepted/rejected counts and errors; do not retry the entire batch. Add --json to inspect the response as {status, headers, body}.

Older self-hosted API snapshots accept a single score object. Select the matching --api-version and run api scores create --help for an example of that snapshot's body shape. The API snapshot version is separate from the CLI package version.

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.

About

Interact with the full Langfuse API from the command line. Built for AI agents and power users.

Topics

Resources

Stars

71 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages