Interact with the Langfuse API from the command line.
# 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.
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 listAlternatively, 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 listFlags 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.
# 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 listV3 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.
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.jsonTo 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.
(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 |
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 updateSkills 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 productionPush 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 --jsonDry 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 --jsonlangfuse skills push ./path/to/skills --recursive --no-lockfileThe latest Langfuse skill lives in langfuse/skills. Print the current version with:
langfuse get-skillThis 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.
See the full Langfuse API Reference.
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.
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.