langfuse-agent-cli 0.3.0__py3-none-any.whl

langfuse_agent_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: langfuse-agent-cli
+Version: 0.3.0
+Summary: Agent-oriented CLI and skill for Langfuse traces, prompts, datasets and scores.
+Author-email: Tarkeshwar Narayan <122815908+tns15june@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tns15june/langfuse-agent-cli
+Project-URL: Repository, https://github.com/tns15june/langfuse-agent-cli
+Project-URL: Issues, https://github.com/tns15june/langfuse-agent-cli/issues
+Keywords: langfuse,llm,observability,agent,cli,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# langfuse-agent-cli (`lf`)
+
+Command-line access to [Langfuse](https://langfuse.com) traces, prompts, datasets and scores, shaped
+for AI coding agents: JSON by default (`--compact` trims it), failing traces with their error messages
+in one command, a trace as a tree, and an agent skill that teaches the commands.
+
+> **Status: prototype.** Langfuse ships an official CLI,
+> [`@langfuse/cli`](https://github.com/langfuse/langfuse-cli), which covers the whole API, and official
+> agent skills, [`langfuse/skills`](https://github.com/langfuse/skills). This project tries out
+> agent-oriented features on the same API.
+> [RFC.md](https://github.com/tns15june/langfuse-agent-cli/blob/main/RFC.md) describes which of them it
+> proposes upstream.
+
+## Requirements
+
+- Python 3.10 or newer
+- Langfuse v4, self-hosted or Cloud. The trace commands read `/api/public/v2/observations`;
+  `lf doctor` reports if a server does not have it.
+- Node.js 22.20 or newer, only for installing the agent skill
+
+## Install
+
+```bash
+pipx install langfuse-agent-cli   # or: uv tool install langfuse-agent-cli
+lf setup
+```
+
+`lf setup` takes three steps and is safe to run again:
+
+1. **Credentials.** It keeps working credentials that it finds. When no profile is saved, or the
+   saved profile's keys are rejected, it asks for the host and the keys (the secret is not echoed)
+   and saves them. It never replaces saved keys when the server is merely unreachable, and keys from
+   `LANGFUSE_*` variables, `--env-file` or key flags, which take precedence over profiles, are left for
+   you to fix.
+2. **Agent skill.** It installs the `langfuse-agent-cli` skill with the
+   [skills CLI](https://github.com/vercel-labs/skills), which asks which coding agents to install it
+   for when it finds more than one. The skill comes from the release tag that matches your `lf`
+   version.
+3. **Check.** It runs `lf doctor`.
+
+To have a coding agent install it, give the agent this prompt:
+
+```text
+Install langfuse-agent-cli by following https://raw.githubusercontent.com/tns15june/langfuse-agent-cli/main/INSTALL.md
+```
+
+The agent installs the CLI and runs `lf setup --yes`, which never prompts and installs the skill for
+that agent. If no working credentials are configured, the agent asks you to run `lf setup` yourself,
+which asks for the host and the keys.
+
+To install the latest code from GitHub instead of PyPI:
+`pipx install git+https://github.com/tns15june/langfuse-agent-cli`.
+
+### Upgrade and uninstall
+
+```bash
+pipx upgrade langfuse-agent-cli && lf setup   # lf setup also installs the matching skill
+npx skills remove --global langfuse-agent-cli
+pipx uninstall langfuse-agent-cli
+```
+
+With uv, use `uv tool upgrade langfuse-agent-cli` and `uv tool uninstall langfuse-agent-cli`. Saved
+profiles stay in `~/.config/langfuse/profiles.json` until you delete that file.
+
+## Credentials
+
+`lf` takes the host and both keys from one source; the first match wins:
+
+1. `--env-file <path>`
+2. `--profile <name>` or `LANGFUSE_PROFILE`
+3. `LANGFUSE_PUBLIC_KEY` or `LANGFUSE_SECRET_KEY` (either one selects this source), with the host from
+   `LANGFUSE_BASE_URL`, then `LANGFUSE_HOST` (default `https://cloud.langfuse.com`)
+4. The saved current profile
+
+`--host`, `--public-key` and `--secret-key` override single values; prefer environment variables or a
+profile over passing keys on the command line, where they end up in shell history. `lf` reads a
+`.env` file only when it is passed with `--env-file`.
+
+To save another profile (the keys are prompted for, and the secret is not echoed):
+
+```bash
+lf auth login --profile-name local --host http://localhost:3000 --default
+lf doctor
+```
+
+Profiles live in `~/.config/langfuse/profiles.json`, readable only by you (mode 0600).
+
+## Commands
+
+Data commands print JSON by default and short lines with `-o text`; `doctor`, `setup`, `auth` and
+`help-map` print text. Three options keep JSON small:
+
+- `--compact` drops null and empty fields.
+- `--agent-fields name,level` keeps only the listed fields of each row.
+- `--output-summary` writes JSON output over 16 KB to a file and prints the file's path, size and keys
+  instead.
+
+```bash
+# Failing traces, one entry per trace, with each error message
+lf trace list --status error --limit 10 --compact
+
+# One trace as a tree; add --io for short inputs and outputs
+lf trace get <trace-id> --timeline
+
+# A trace with its inputs and outputs; over 16 KB it goes to a file
+lf trace get <trace-id> --io --output-summary
+
+# The traces of a session, oldest first (the newest 1000)
+lf trace session <session-id> --compact
+
+# Recent traces, filtered
+lf trace list --user-id user-42 --from-ts 2026-10-24T00:00:00Z --limit 20
+
+# Prompts
+lf prompt list -o text
+lf prompt get support/greeter
+lf prompt get welcome-bot --vars '{"user_name": "Alice", "plan": "pro"}' -o text
+lf prompt push welcome-bot --text 'Hello {{user_name}}!' --labels staging
+
+# Datasets and scores
+lf dataset list
+lf dataset get intent-classification-evals
+lf score create --trace-id <trace-id> --name accuracy --value 1
+
+# Discover commands and options
+lf help-map
+lf help "trace get"
+```
+
+A timeline, from synthetic data:
+
+```text
+Trace 33579e8e8ec602e878f0744ad53ac1fe: 3 observations, 1 error
+✓ AGENT support-agent-turn
+  ✓ GENERATION plan-step (model: gpt-4o-mini)
+  ✗ [ERROR] TOOL search_tool_call
+      Message: 503 Service Unavailable
+```
+
+Observations with a measured duration show it in brackets, such as `[1.24s]`. Langfuse 4.70 reports
+no duration for observations of zero length, like these synthetic ones.
+
+Exit codes: `0` success, `1` API or configuration error, `2` invalid command. The reason for a failure is
+on stderr, except that `doctor`, `setup --yes` and `auth status` print their whole report, failures
+included, on stdout. `setup` also exits `1` when the skill was not installed.
+
+## API endpoints used
+
+| Command | Endpoint |
+| --- | --- |
+| `trace list` | `GET /api/public/v2/observations?isRootObservation=true` |
+| `trace list --status error` | `GET /api/public/v2/observations?level=ERROR`, grouped by trace |
+| `trace get` | `GET /api/public/v2/observations?traceId=…`, all pages |
+| `trace session` | `GET /api/public/v2/observations?sessionId=…&isRootObservation=true` |
+| `prompt list`, `prompt get`, `prompt push` | `/api/public/v2/prompts` |
+| `dataset list`, `dataset get` | `/api/public/v2/datasets`, `/api/public/dataset-items` |
+| `score create` | `POST /api/public/scores` |
+| `doctor` | `/api/public/health`, `/api/public/projects`, `/api/public/v2/observations?limit=1` |
+| `auth login`, `auth status` | `/api/public/projects` |
+| `setup` | `/api/public/projects`, then the `doctor` requests |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest -q
+```
+
+The unit tests replay responses recorded from Langfuse 4.70.0 (synthetic data). The live tests run
+every command against a real instance, for example one started from Langfuse's official
+`docker-compose.yml`:
+
+```bash
+export LANGFUSE_BASE_URL=http://localhost:3000 LANGFUSE_PUBLIC_KEY=pk-lf-... LANGFUSE_SECRET_KEY=sk-lf-...
+pip install langfuse
+python scripts/seed_langfuse.py   # synthetic prompts, a dataset and traces: use a throwaway project
+LF_LIVE=1 pytest tests/test_live.py -v
+```
+
+CI runs the unit tests on Python 3.10 to 3.13 and the live tests against the latest Langfuse release,
+on every push and weekly.
+
+### Releasing
+
+The Publish workflow uploads to PyPI with trusted publishing, so no token is stored; the PyPI project
+lists `publish.yml` and the GitHub environment `pypi` as its trusted publisher. Bump `__version__` in
+`langfuse_cli/__init__.py`, commit, then push that commit and its tag together:
+
+```bash
+git tag v0.3.0 && git push --atomic origin main v0.3.0
+```
+
+The workflow checks that the tag matches the version, runs the tests, builds and checks the
+distributions, installs the wheel, and uploads the wheel and the source archive. `main` should never
+carry a version without its tag, because `lf setup` and `lf doctor` point at the skill under that tag.
+
+## Prior art
+
+The command map (`lf help-map`), the `--output-summary` option, `lf setup` and the agent install prompt
+follow Atlassian's
+[Teamwork Graph CLI](https://developer.atlassian.com/platform/teamwork-graph/twg-cli/getting-started/installation/),
+whose `--select` option does what `lf`'s `--agent-fields` does.
+
+## License
+
+MIT

langfuse_agent_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+langfuse_agent_cli-0.3.0.dist-info/licenses/LICENSE,sha256=9nIkgumqkB1u89JeP4O9VdtrVyVLvXO8cvxDix2GEKY,1075
+langfuse_cli/__init__.py,sha256=4tkLLiPD61IoWp3dkCTcboDjPGC_FUVinOGMs2Hopik,56
+langfuse_cli/__main__.py,sha256=TdqB9UA_fmdjrh94qBuh5_OhVjYL9Y_R7-OIW8ebMa8,141
+langfuse_cli/cli.py,sha256=ttXX0Hmzy8KDHpPM2_kzGQJkhPGD6AVJHyDw0QEN5pc,10169
+langfuse_cli/client.py,sha256=e8PwSdSZgQ4vHp6iBrD3Tkr6aRkkhBZ_1WtWsIocK5Y,7881
+langfuse_cli/config.py,sha256=6K0VCRUM3S7ys_JLJ3_Hv7vwAueVN0SwF2FjJUVGD3c,7024
+langfuse_cli/commands/__init__.py,sha256=KmuWdd_HmO2m_9qdcN4tCNAkK6tMti7Lu3wHTTpUz5c,41
+langfuse_cli/commands/auth.py,sha256=nM18xNiSTLMS13dpDN_H7Hl-C9fKFoXsTEj5GlHu34c,3617
+langfuse_cli/commands/dataset.py,sha256=l3ZDVPyDtpSvuHiyirytdFAKCmeYtfBNl8DpKNTvJXQ,1419
+langfuse_cli/commands/doctor.py,sha256=E8JNwJQQvFTdeUBtXfTNPNsM8rFzwEQeSIIIG1etPkY,3737
+langfuse_cli/commands/help_map.py,sha256=LkRWx_pvRItttezTICSCVIbGMoOM0eRdwl7HN-UHQeI,6785
+langfuse_cli/commands/prompt.py,sha256=8bIQL3aedHSDl36VjGFV_zO6dITbJIetfgkNaFdhpcM,4885
+langfuse_cli/commands/score.py,sha256=iJJomKkxyTTVpMWcWQ8VHxedS5tazgtSzS3WuTKPFw8,722
+langfuse_cli/commands/setup.py,sha256=k9IgLydHGEsI4f89vFvol7eYVxMHcHLsG2FVip-hLGg,5151
+langfuse_cli/commands/trace.py,sha256=r8_Mfr_XnpLqudDh_Gu48ZJ8D7b_lAWqIryAQ6H1V9E,4244
+langfuse_cli/formatters/__init__.py,sha256=hRVMMENxKY6y0hWKT6tpmDqY3y23qM3SY68DZiymIvs,701
+langfuse_cli/formatters/agent.py,sha256=dj-jDNHxY06lEwX81v-7P8XAaLMm3YCrX3q5PBhvN3A,3900
+langfuse_cli/formatters/timeline.py,sha256=kntmxvpwMV027927EVY4Eq5mrPJrtUXMoivWB2sCO_I,2106
+langfuse_agent_cli-0.3.0.dist-info/METADATA,sha256=eOnsEdwtjdG_54jnGB9e2BqgHjzUWpTxLR_DZHOLc6Y,9546
+langfuse_agent_cli-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+langfuse_agent_cli-0.3.0.dist-info/entry_points.txt,sha256=izFtfLvAQLMy90cHykh16bjzZ9xW7Rey09tCcOMX6Kk,45
+langfuse_agent_cli-0.3.0.dist-info/top_level.txt,sha256=-VrFPWF0TnKyWSILzdVTq6U8oz6ydPVE4PM9Ev8Ozyc,13
+langfuse_agent_cli-0.3.0.dist-info/RECORD,,

langfuse_agent_cli-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

langfuse_agent_cli-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lf = langfuse_cli.cli:main

langfuse_agent_cli-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tarkeshwar Narayan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langfuse_agent_cli-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+langfuse_cli

langfuse_cli/__init__.py

@@ -0,0 +1,2 @@
+"""Langfuse Agent CLI package."""
+__version__ = "0.3.0"

langfuse_cli/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for python -m langfuse_cli."""
+import sys
+
+from langfuse_cli.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

langfuse_cli/cli.py

@@ -0,0 +1,197 @@
+"""Main CLI entrypoint for Langfuse Agent CLI."""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from langfuse_cli import __version__
+from langfuse_cli.client import LangfuseAPIError
+from langfuse_cli.commands.auth import handle_auth
+from langfuse_cli.commands.dataset import handle_dataset
+from langfuse_cli.commands.doctor import handle_doctor
+from langfuse_cli.commands.help_map import handle_help_describe, handle_help_map
+from langfuse_cli.commands.prompt import handle_prompt
+from langfuse_cli.commands.score import handle_score
+from langfuse_cli.commands.setup import handle_setup
+from langfuse_cli.commands.trace import handle_trace
+from langfuse_cli.config import ConfigError
+from langfuse_cli.formatters import clean
+
+# Common options use argparse.SUPPRESS so a subcommand's default never overwrites a value given
+# before the subcommand; these defaults are applied once after parsing instead.
+COMMON_DEFAULTS = {
+    "profile": None,
+    "host": None,
+    "public_key": None,
+    "secret_key": None,
+    "env_file": None,
+    "output": "json",
+    "compact": False,
+    "agent_fields": None,
+    "output_summary": False,
+}
+
+
+class _SafeStream:
+    """Wraps stdout/stderr so nothing a command prints, server data included, can drive the terminal."""
+
+    def __init__(self, stream):
+        self._stream = stream
+
+    def write(self, text: str) -> int:
+        return self._stream.write(clean(text))
+
+    def __getattr__(self, name):
+        return getattr(self._stream, name)
+
+
+def create_parser() -> argparse.ArgumentParser:
+    common_parser = argparse.ArgumentParser(add_help=False)
+    common = common_parser.add_argument
+    unset = argparse.SUPPRESS  # defaults come from COMMON_DEFAULTS
+    common("-p", "--profile", default=unset, help="Saved profile to use (see 'lf auth list')")
+    common("--host", default=unset, help="Langfuse host, e.g. http://localhost:3000")
+    common("--public-key", default=unset, help="Langfuse public key (pk-lf-...)")
+    common("--secret-key", default=unset, help="Langfuse secret key (sk-lf-...); prefer env vars or a profile")
+    common("--env-file", default=unset, help="Read LANGFUSE_* credentials from this .env file")
+    common("-o", "--output", choices=["json", "text"], default=unset, help="Output format (default: json)")
+    common("--compact", action="store_true", default=unset, help="Drop null and empty fields from JSON output")
+    common("--agent-fields", default=unset, help="Comma-separated field paths to keep in JSON output")
+    common("--output-summary", action="store_true", default=unset,
+           help="With JSON output, write output over 16 KB to a file and print its path, size and keys instead")
+
+    parser = argparse.ArgumentParser(
+        prog="lf",
+        description="Agent-oriented CLI for Langfuse traces, prompts, datasets and scores.",
+        parents=[common_parser],
+    )
+    parser.add_argument("-v", "--version", action="version", version=f"lf {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available command families")
+
+    # 1. Auth command
+    p_auth = subparsers.add_parser("auth", parents=[common_parser], help="Manage authentication profiles")
+    auth_sub = p_auth.add_subparsers(dest="auth_action", required=True)
+    p_auth_login = auth_sub.add_parser("login", parents=[common_parser], help="Save a profile")
+    p_auth_login.add_argument("--profile-name", help="Profile name (default: default)")
+    p_auth_login.add_argument("--default", action="store_true", help="Set as default active profile")
+
+    p_auth_switch = auth_sub.add_parser("switch", parents=[common_parser], help="Switch active profile")
+    p_auth_switch.add_argument("target_profile", help="Profile name to activate")
+
+    auth_sub.add_parser("list", parents=[common_parser], help="List configured profiles")
+    auth_sub.add_parser("status", parents=[common_parser], help="Check current profile status and connectivity")
+
+    # 2. Doctor and setup
+    subparsers.add_parser("doctor", parents=[common_parser], help="Check credentials, server and the agent skill")
+    p_setup = subparsers.add_parser("setup", parents=[common_parser],
+                                    help="Log in, install the agent skill and run doctor")
+    p_setup.add_argument("-y", "--yes", action="store_true",
+                         help="Never prompt: skip login when no working credentials are found and install the skill "
+                              "without asking")
+
+    # 3. Prompt command
+    p_prompt = subparsers.add_parser("prompt", parents=[common_parser], help="Inspect and manage prompt versions")
+    prompt_sub = p_prompt.add_subparsers(dest="prompt_action", required=True)
+
+    p_prompt_list = prompt_sub.add_parser("list", parents=[common_parser], help="List registered prompts")
+    p_prompt_list.add_argument("--tag", help="Filter prompts by tag")
+    p_prompt_list.add_argument("--limit", type=int, default=20, help="Maximum prompts to return")
+
+    p_prompt_get = prompt_sub.add_parser("get", parents=[common_parser], help="Fetch a prompt by name")
+    p_prompt_get.add_argument("name", help="Prompt name in Langfuse")
+    p_prompt_get.add_argument("--version", type=int, help="Prompt version number")
+    p_prompt_get.add_argument("--label", help="Prompt label (e.g. production, staging)")
+    p_prompt_get.add_argument("--vars", help="JSON dictionary of variables to compile into {{mustache}} template")
+
+    p_prompt_push = prompt_sub.add_parser("push", parents=[common_parser], help="Publish a new prompt version")
+    p_prompt_push.add_argument("name", help="Prompt name")
+    p_prompt_push.add_argument("--file", help="Path to file containing prompt text or chat JSON")
+    p_prompt_push.add_argument("--text", help="Raw prompt string")
+    p_prompt_push.add_argument("--type", choices=["text", "chat"], default="text", help="Prompt format type")
+    p_prompt_push.add_argument("--labels", help="Comma-separated labels (e.g. staging,v2)")
+    p_prompt_push.add_argument("--tags", help="Comma-separated tags")
+
+    # 4. Trace command
+    p_trace = subparsers.add_parser("trace", parents=[common_parser], help="Observability and trace inspection")
+    trace_sub = p_trace.add_subparsers(dest="trace_action", required=True)
+
+    p_trace_list = trace_sub.add_parser("list", parents=[common_parser], help="List recent traces")
+    p_trace_list.add_argument("--session-id", help="Filter by session ID")
+    p_trace_list.add_argument("--user-id", help="Filter by user ID")
+    p_trace_list.add_argument("--status", choices=["all", "error"], default="all", help="Filter traces (e.g. error)")
+    p_trace_list.add_argument("--limit", type=int, default=20, help="Maximum traces to return")
+    p_trace_list.add_argument("--from-ts", help="Start timestamp ISO8601")
+    p_trace_list.add_argument("--to-ts", help="End timestamp ISO8601")
+
+    p_trace_get = trace_sub.add_parser("get", parents=[common_parser], help="Get trace details")
+    p_trace_get.add_argument("trace_id", help="Trace ID")
+    p_trace_get.add_argument("--timeline", action="store_true", help="Display visual timeline tree")
+    p_trace_get.add_argument("--io", action="store_true", help="Include observation inputs and outputs (large)")
+
+    p_trace_session = trace_sub.add_parser("session", parents=[common_parser], help="Get traces for an entire session")
+    p_trace_session.add_argument("session_id", help="Session ID")
+
+    # 5. Dataset command
+    p_dataset = subparsers.add_parser("dataset", parents=[common_parser], help="Manage datasets and test suites")
+    dataset_sub = p_dataset.add_subparsers(dest="dataset_action", required=True)
+
+    dataset_sub.add_parser("list", parents=[common_parser], help="List datasets")
+    p_dataset_get = dataset_sub.add_parser("get", parents=[common_parser], help="Get dataset items")
+    p_dataset_get.add_argument("name", help="Dataset name")
+
+
+    # 6. Score command
+    p_score = subparsers.add_parser("score", parents=[common_parser], help="Record evaluation scores")
+    score_sub = p_score.add_subparsers(dest="score_action", required=True)
+    p_score_create = score_sub.add_parser("create", parents=[common_parser], help="Create a score on a trace")
+    p_score_create.add_argument("--trace-id", required=True, help="Target trace ID")
+    p_score_create.add_argument("--name", required=True, help="Metric name (e.g. accuracy, relevance)")
+    p_score_create.add_argument("--value", required=True, type=float, help="Numeric value (e.g. 1.0, 0.8)")
+    p_score_create.add_argument("--comment", help="Optional comment explaining score")
+    p_score_create.add_argument("--observation-id", help="Optional observation ID within the trace")
+
+    # 7. Help map and progressive disclosure
+    subparsers.add_parser("help-map", parents=[common_parser],
+                          help="Compact command map for agents (* marks commands that write)")
+    p_help = subparsers.add_parser("help", parents=[common_parser], help="Describe command details")
+    p_help.add_argument("target_command", nargs="+", help="Command to describe (e.g. 'prompt get')")
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+    for key, value in COMMON_DEFAULTS.items():
+        vars(args).setdefault(key, value)
+
+    handlers = {
+        "auth": handle_auth,
+        "doctor": handle_doctor,
+        "setup": handle_setup,
+        "prompt": handle_prompt,
+        "trace": handle_trace,
+        "dataset": handle_dataset,
+        "score": handle_score,
+        "help-map": handle_help_map,
+        "help": handle_help_describe,
+    }
+    streams = sys.stdout, sys.stderr
+    sys.stdout, sys.stderr = _SafeStream(sys.stdout), _SafeStream(sys.stderr)
+    try:
+        return handlers[args.command](args)
+    except (LangfuseAPIError, ConfigError, OSError) as e:  # OSError: --file, the profiles file
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    finally:
+        sys.stdout, sys.stderr = streams
+
+
+if __name__ == "__main__":
+    sys.exit(main())