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

langfuse_cli/commands/prompt.py

@@ -0,0 +1,123 @@
+"""Prompt management commands for Langfuse."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from typing import Any, Dict
+
+from langfuse_cli.client import LangfuseClient
+from langfuse_cli.config import resolve_from_args
+from langfuse_cli.formatters.agent import print_json
+
+
+def compile_mustache(template: str, vars_dict: Dict[str, Any]) -> str:
+    """Basic mustache variable substitution for {{var}}."""
+    result = template
+    for key, val in vars_dict.items():
+        pattern = r"\{\{\s*" + re.escape(key) + r"\s*\}\}"
+        # A function replacement inserts the value as-is; a string one would expand \1, \n and \U in it.
+        result = re.sub(pattern, lambda _match, value=str(val): value, result)
+    return result
+
+
+def compile_prompt(prompt_data: Any, vars_dict: Dict[str, Any]) -> Any:
+    if isinstance(prompt_data, str):
+        return compile_mustache(prompt_data, vars_dict)
+    elif isinstance(prompt_data, list):
+        # Chat messages: [{"role": "user", "content": "..."}]
+        out = []
+        for msg in prompt_data:
+            if isinstance(msg, dict) and "content" in msg and isinstance(msg["content"], str):
+                c = dict(msg)
+                c["content"] = compile_mustache(msg["content"], vars_dict)
+                out.append(c)
+            else:
+                out.append(msg)
+        return out
+    return prompt_data
+
+
+def handle_prompt(args: argparse.Namespace) -> int:
+    client = LangfuseClient(resolve_from_args(args))
+
+    if args.prompt_action == "list":
+        prompts = client.list_prompts(limit=args.limit, tag=args.tag).get("data", [])
+        if args.output == "json":
+            print_json(args, prompts)
+        elif not prompts:
+            print("No prompts found.")
+        else:
+            print(f"Found {len(prompts)} prompts:")
+            for p in prompts:
+                versions = p.get("versions") or []
+                latest = max(versions) if versions else "?"
+                labels = ", ".join(p.get("labels", []))
+                labels_str = f" [labels: {labels}]" if labels else ""
+                print(f"  - {p.get('name')} (v{latest}){labels_str} - type: {p.get('type', 'text')}")
+        return 0
+
+    if args.prompt_action == "get":
+        vars_dict = None
+        if args.vars:
+            try:
+                vars_dict = json.loads(args.vars)
+            except ValueError as e:
+                print(f"Error: --vars is not valid JSON: {e}", file=sys.stderr)
+                return 1
+            if not isinstance(vars_dict, dict):
+                print('Error: --vars must be a JSON object, for example \'{"user_name": "Alice"}\'', file=sys.stderr)
+                return 1
+        prompt = client.get_prompt(name=args.name, version=args.version, label=args.label)
+        if vars_dict is not None:
+            prompt["compiled_prompt"] = compile_prompt(prompt.get("prompt"), vars_dict)
+            prompt["applied_vars"] = vars_dict
+
+        if args.output == "json":
+            print_json(args, prompt)
+        else:
+            print(f"Prompt: {prompt.get('name')} (v{prompt.get('version')})")
+            print(f"Type: {prompt.get('type', 'text')}")
+            if prompt.get("labels"):
+                print(f"Labels: {', '.join(prompt['labels'])}")
+            if prompt.get("tags"):
+                print(f"Tags: {', '.join(prompt['tags'])}")
+            print("-" * 40)
+            display_content = prompt.get("compiled_prompt") or prompt.get("prompt")
+            if isinstance(display_content, (dict, list)):
+                print(json.dumps(display_content, indent=2))
+            else:
+                print(display_content)
+        return 0
+
+    # push
+    if args.file:
+        with open(args.file, "r", encoding="utf-8") as f:
+            content = f.read()
+        if args.type == "chat":
+            try:
+                prompt_content = json.loads(content)
+            except ValueError as e:
+                print(f"Error: --file must hold a JSON list of messages for --type chat: {e}", file=sys.stderr)
+                return 1
+        else:
+            prompt_content = content  # a text prompt is sent as written, even when it looks like JSON
+    elif args.text:
+        prompt_content = args.text
+    else:
+        print("Error: Specify either --file <path> or --text '<prompt string>'", file=sys.stderr)
+        return 1
+
+    created = client.create_prompt(
+        name=args.name,
+        prompt_content=prompt_content,
+        prompt_type=args.type,
+        labels=[label.strip() for label in args.labels.split(",")] if args.labels else None,
+        tags=[tag.strip() for tag in args.tags.split(",")] if args.tags else None,
+    )
+    if args.output == "json":
+        print_json(args, created)
+    else:
+        print(f"✓ Prompt '{args.name}' (v{created.get('version', 'new')}) published successfully.")
+    return 0

langfuse_cli/commands/score.py

@@ -0,0 +1,24 @@
+"""Score and evaluation metric commands."""
+from __future__ import annotations
+
+import argparse
+
+from langfuse_cli.client import LangfuseClient
+from langfuse_cli.config import resolve_from_args
+from langfuse_cli.formatters.agent import print_json
+
+
+def handle_score(args: argparse.Namespace) -> int:
+    client = LangfuseClient(resolve_from_args(args))
+    res = client.create_score(
+        trace_id=args.trace_id,
+        name=args.name,
+        value=args.value,
+        comment=args.comment,
+        observation_id=args.observation_id,
+    )
+    if args.output == "json":
+        print_json(args, res)
+    else:
+        print(f"✓ Score '{args.name}'={args.value} recorded for trace '{args.trace_id}'.")
+    return 0

langfuse_cli/commands/setup.py

@@ -0,0 +1,101 @@
+"""One-step setup: credentials, the agent skill, then doctor."""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+
+from langfuse_cli.client import LangfuseAPIError, LangfuseClient
+from langfuse_cli.commands.auth import login
+from langfuse_cli.commands.doctor import SKILL_NAME, SKILL_SOURCE, handle_doctor
+from langfuse_cli.config import ConfigError, ConfigManager, resolve_from_args
+
+INSTALL_LATER = f"  To install it later: npx skills@1 add {SKILL_SOURCE} -g"
+SOURCE_NAMES = {"env": "the LANGFUSE_* environment variables", "env-file": "the --env-file file",
+                "flags": "--public-key and --secret-key"}
+
+
+def _credentials(args: argparse.Namespace, interactive: bool) -> None:
+    try:
+        prof = resolve_from_args(args)
+    except ConfigError as e:  # doctor reports it again; the skill step still runs
+        print(f"  ✗ {e}")
+        return
+    rejected = True  # missing keys count as rejected
+    if prof.is_complete():
+        try:
+            projects = LangfuseClient(prof).get_project().get("data") or []
+        except LangfuseAPIError as e:
+            print(f"  ✗ {e}")
+            rejected = e.status_code in (401, 403)
+        else:
+            names = ", ".join(p.get("name", "?") for p in projects) or "(none)"
+            print(f"  ✓ Using {prof.source} credentials for {prof.host} (project: {names})")
+            return
+    if not rejected:  # new keys would not help; asking for them invites overwriting good ones
+        print("  – Login skipped: the keys were not rejected; check the host and that the server is up.")
+    elif prof.source != "profile":  # these sources outrank saved profiles, so a login here would change nothing
+        print(f"  – Login skipped: these keys come from {SOURCE_NAMES[prof.source]}, which take precedence over "
+              "saved profiles. Fix or unset them, then run lf setup again.")
+    elif not interactive:
+        print("  – Login skipped: lf setup never asks for keys with --yes or without a terminal. "
+              "Ask the user to run 'lf setup' in their own terminal.")
+    else:
+        host = input(f"  Langfuse host [{prof.host}]: ").strip() or prof.host
+        login(ConfigManager(), prof.name, host, None, None, set_default=True)  # keys that failed are asked for again
+
+
+def _install_skill(interactive: bool) -> bool:
+    """Install the skill with the skills CLI; False when it could not be installed (declining is not a failure)."""
+    npx = shutil.which("npx")
+    if npx is None:
+        print("  ✗ npx not found; the skills CLI needs Node.js 22.20 or later.")
+        print(INSTALL_LATER)
+        return False
+    # On Windows, which() searches the current folder first; never run an npx that a project folder supplies.
+    if os.path.normcase(os.path.realpath(os.path.dirname(npx))) == os.path.normcase(os.path.realpath(os.getcwd())):
+        print(f"  ✗ Not running {npx}: it is in the current folder. Run lf setup from another folder.")
+        print(INSTALL_LATER)
+        return False
+    if interactive and input(f"  Install the {SKILL_NAME} skill for your coding agents? [Y/n] ").strip().lower() in (
+            "n", "no"):
+        print(INSTALL_LATER)
+        return True
+    # npx --yes skips npm's install prompt. The skills CLI's own -y skips its questions: without it, it asks which
+    # agents to use when it finds several; with it, it takes the agents it finds, or every agent it supports when it
+    # finds none. Run from inside a coding agent, it targets that agent either way.
+    cmd = [npx, "--yes", "skills@1", "add", SKILL_SOURCE, "-g"]
+    if not interactive:
+        cmd.append("-y")
+    # No LANGFUSE_* keys for npx and the install scripts it runs; git must fail rather than wait for a password.
+    env = {k: v for k, v in os.environ.items() if not k.startswith("LANGFUSE_")}
+    env["GIT_TERMINAL_PROMPT"] = "0"
+    print(f"  Running: npx {' '.join(cmd[1:])}", flush=True)
+    try:
+        # Unattended runs get no stdin and 90 s, so they end inside an agent's usual 2-minute command limit.
+        result = subprocess.run(cmd, env=env, stdin=None if interactive else subprocess.DEVNULL,
+                                timeout=None if interactive else 90)
+        reason = f"npx exited with code {result.returncode}" if result.returncode else ""
+    except (subprocess.TimeoutExpired, OSError) as e:  # OSError: npx was found but could not be started
+        reason = str(e)
+    if reason:
+        print(f"  ✗ The skill was not installed: {reason}")
+        print(INSTALL_LATER)
+    return not reason
+
+
+def handle_setup(args: argparse.Namespace) -> int:
+    interactive = not args.yes and sys.stdin is not None and sys.stdin.isatty()
+    print("\nLangfuse Agent CLI Setup")
+    print("\n1. Credentials")
+    _credentials(args, interactive)
+    print("\n2. Agent Skill")
+    installed = _install_skill(interactive)
+    print("\n3. Check")
+    code = handle_doctor(args)
+    if not installed:
+        print("  ✗ lf setup did not install the skill (see step 2); any copy listed above is from an earlier install.")
+        return 1
+    return code

langfuse_cli/commands/trace.py

@@ -0,0 +1,83 @@
+"""Trace commands, read through the observations v2 API (the only trace read path on Langfuse v4)."""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any, Dict, Iterable, List
+
+from langfuse_cli.client import LangfuseClient
+from langfuse_cli.config import resolve_from_args
+from langfuse_cli.formatters.agent import print_json
+from langfuse_cli.formatters.timeline import render_trace_timeline
+
+# Field groups of GET /api/public/v2/observations. "metrics" carries latency; the spec puts it there.
+# Langfuse 4.70 returns latency null instead of 0 for zero-length observations when "metrics" is requested.
+ROOT_FIELDS = "core,basic,metrics"  # a trace is listed as its root observation
+TREE_FIELDS = "core,basic,time,model,usage,metrics"  # leaves out io (--io adds it), metadata, prompt, trace_context
+
+
+def group_errors(observations: Iterable[Dict[str, Any]], limit: int) -> List[Dict[str, Any]]:
+    """ERROR observations grouped by trace in first-seen order, at most `limit` traces."""
+    groups: Dict[Any, Dict[str, Any]] = {}
+    for obs in observations:
+        trace_id = obs.get("traceId")
+        if trace_id not in groups:
+            if len(groups) == limit:
+                break  # stops the lazy page iterator too
+            groups[trace_id] = {"traceId": trace_id, "sessionId": obs.get("sessionId"),
+                                "userId": obs.get("userId"), "errors": []}
+        groups[trace_id]["errors"].append({k: obs.get(k) for k in ("id", "name", "type", "statusMessage", "startTime")})
+    return list(groups.values())
+
+
+def _trace_line(row: Dict[str, Any]) -> str:
+    latency = f" ({float(row['latency']):.2f}s)" if row.get("latency") is not None else ""
+    return f"  - [{row.get('traceId')}] {row.get('name') or 'unnamed'}{latency} @ {row.get('startTime')}"
+
+
+def _emit(args: argparse.Namespace, rows: List[Dict[str, Any]], lines: List[str], empty: str) -> int:
+    if args.output == "json":
+        print_json(args, rows)
+    else:
+        print("\n".join(lines) if lines else empty)
+    return 0
+
+
+def _by_start(obs: Dict[str, Any]) -> str:
+    return obs.get("startTime") or ""
+
+
+def handle_trace(args: argparse.Namespace) -> int:
+    client = LangfuseClient(resolve_from_args(args))
+
+    if args.trace_action == "list":
+        filters = {"sessionId": args.session_id, "userId": args.user_id,
+                   "fromStartTime": args.from_ts, "toStartTime": args.to_ts}
+        if args.status == "error":
+            # shortcut: scans at most 5000 error rows; raise the cap if busy projects need longer windows
+            errors = client.iter_observations({**filters, "level": "ERROR", "fields": ROOT_FIELDS}, max_items=5000)
+            rows = group_errors(errors, args.limit)
+            lines = [f"  - [{g['traceId']}] {len(g['errors'])} error(s): "
+                     + "; ".join(f"{e['name']}: {e['statusMessage']}" for e in g["errors"]) for g in rows]
+            return _emit(args, rows, lines, "No traces with errors found.")
+        rows = client.list_observations(**filters, isRootObservation=True, fields=ROOT_FIELDS, limit=args.limit)
+        rows = rows.get("data", [])
+        return _emit(args, rows, [_trace_line(r) for r in rows], "No traces found.")
+
+    if args.trace_action == "get":
+        fields = TREE_FIELDS + (",io" if args.io else "")
+        observations = sorted(client.iter_observations({"traceId": args.trace_id, "fields": fields}), key=_by_start)
+        if not observations:
+            print(f"Error: trace {args.trace_id} not found", file=sys.stderr)
+            return 1
+        if args.timeline or args.output == "text":
+            print(render_trace_timeline(args.trace_id, observations))
+        else:
+            print_json(args, observations)
+        return 0
+
+    # session: its traces, oldest first, so a conversation reads top to bottom
+    # shortcut: keeps the newest 1000 traces (the API returns newest first); page further if sessions grow
+    params = {"sessionId": args.session_id, "isRootObservation": True, "fields": ROOT_FIELDS}
+    rows = sorted(client.iter_observations(params, max_items=1000), key=_by_start)
+    return _emit(args, rows, [_trace_line(r) for r in rows], f"No traces in session {args.session_id}.")

langfuse_cli/config.py

@@ -0,0 +1,187 @@
+"""Configuration and profile management for Langfuse CLI."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+DEFAULT_CONFIG_DIR = Path.home() / ".config" / "langfuse"
+DEFAULT_PROFILES_FILE = DEFAULT_CONFIG_DIR / "profiles.json"
+
+
+class ConfigError(Exception):
+    """Credentials or the profiles file cannot be used as given."""
+
+
+@dataclass
+class ProfileConfig:
+    name: str
+    host: str
+    public_key: str
+    secret_key: str
+    source: str = ""  # "profile", "env" or "env-file"; "flags" when both keys come from flags
+
+    def is_complete(self) -> bool:
+        return bool(self.host and self.public_key and self.secret_key)
+
+    def masked_public_key(self) -> str:
+        if not self.public_key:
+            return "(not set)"
+        if len(self.public_key) <= 8:
+            return "******"
+        return f"{self.public_key[:6]}...{self.public_key[-4:]}"
+
+    def masked_secret_key(self) -> str:
+        if not self.secret_key:
+            return "(not set)"
+        if len(self.secret_key) <= 8:
+            return "******"
+        return f"{self.secret_key[:6]}...{self.secret_key[-4:]}"
+
+
+class ConfigManager:
+    """Manages persistent profiles and active session configurations."""
+
+    def __init__(self, config_path: Optional[Path] = None):
+        self.config_path = config_path or DEFAULT_PROFILES_FILE
+        self._cache: Optional[Dict[str, Any]] = None
+
+    def _load_raw(self) -> Dict[str, Any]:
+        if self._cache is not None:
+            return self._cache
+        data: Any = {}
+        if self.config_path.exists():
+            try:
+                data = json.loads(self.config_path.read_text(encoding="utf-8"))
+            except ValueError as e:
+                # Refuse to continue: the next save would silently drop every saved profile.
+                raise ConfigError(f"{self.config_path} is not valid JSON; fix or delete it") from e
+            if not isinstance(data, dict):
+                raise ConfigError(f"{self.config_path} is not a profiles file; fix or delete it")
+        data.setdefault("current_profile", "default")
+        data.setdefault("profiles", {})
+        self._cache = data
+        return data
+
+    def _save_raw(self, data: Dict[str, Any]) -> None:
+        # The file holds secret keys: create directory and file private from the start, then swap it in.
+        self.config_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=self.config_path.parent, prefix=".profiles-")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+            os.replace(tmp, self.config_path)
+        except BaseException:
+            os.unlink(tmp)
+            raise
+        self._cache = data
+
+    def list_profiles(self) -> Dict[str, ProfileConfig]:
+        data = self._load_raw()
+        profiles = {}
+        for name, p in data.get("profiles", {}).items():
+            profiles[name] = ProfileConfig(
+                name=name,
+                host=p.get("host", ""),
+                public_key=p.get("public_key", ""),
+                secret_key=p.get("secret_key", ""),
+                source="profile",
+            )
+        return profiles
+
+    def get_current_profile_name(self) -> str:
+        return self._load_raw().get("current_profile", "default")
+
+    def set_current_profile(self, name: str) -> None:
+        data = self._load_raw()
+        data["current_profile"] = name
+        self._save_raw(data)
+
+    def save_profile(
+        self,
+        name: str,
+        host: str,
+        public_key: str,
+        secret_key: str,
+        set_default: bool = False,
+    ) -> None:
+        data = self._load_raw()
+        clean_host = host.rstrip("/")
+        data["profiles"][name] = {
+            "host": clean_host,
+            "public_key": public_key,
+            "secret_key": secret_key,
+        }
+        if set_default or len(data["profiles"]) == 1:
+            data["current_profile"] = name
+        self._save_raw(data)
+
+    def resolve_profile(
+        self,
+        name: Optional[str] = None,
+        host_override: Optional[str] = None,
+        pk_override: Optional[str] = None,
+        sk_override: Optional[str] = None,
+        env_file: Optional[str] = None,
+    ) -> ProfileConfig:
+        """Take host and keys from one source, then apply explicit flag overrides.
+
+        Sources, first match wins: --env-file, --profile / LANGFUSE_PROFILE, the environment (when
+        LANGFUSE_PUBLIC_KEY or LANGFUSE_SECRET_KEY is set), the saved current profile. Sources are
+        never mixed, so a host found in one place (a cloned repo's .env, say) cannot receive keys that
+        came from another.
+        """
+        explicit = name or os.environ.get("LANGFUSE_PROFILE")
+        if env_file:
+            base = self._from_vars(self._parse_dotenv(env_file), "env-file")
+        elif explicit:
+            base = self.list_profiles().get(explicit)
+            if base is None:
+                raise ConfigError(f"profile '{explicit}' not found; see 'lf auth list'")
+        elif os.environ.get("LANGFUSE_PUBLIC_KEY") or os.environ.get("LANGFUSE_SECRET_KEY"):
+            base = self._from_vars(os.environ, "env")
+        else:
+            current = self.get_current_profile_name()
+            base = self.list_profiles().get(current) or ProfileConfig(current, "", "", "", "profile")
+
+        return ProfileConfig(
+            name=base.name,
+            host=(host_override or base.host or "https://cloud.langfuse.com").rstrip("/"),
+            public_key=pk_override or base.public_key,
+            secret_key=sk_override or base.secret_key,
+            source="flags" if pk_override and sk_override else base.source,
+        )
+
+    @staticmethod
+    def _from_vars(values: Any, source: str) -> ProfileConfig:
+        return ProfileConfig(
+            name="",
+            host=values.get("LANGFUSE_BASE_URL") or values.get("LANGFUSE_HOST") or "",
+            public_key=values.get("LANGFUSE_PUBLIC_KEY", ""),
+            secret_key=values.get("LANGFUSE_SECRET_KEY", ""),
+            source=source,
+        )
+
+    @staticmethod
+    def _parse_dotenv(path: str) -> Dict[str, str]:
+        try:
+            lines = Path(path).read_text(encoding="utf-8").splitlines()
+        except OSError as e:
+            raise ConfigError(f"cannot read env file {path}: {e}") from e
+        res = {}
+        for line in lines:
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, v = line.split("=", 1)
+            res[k.strip()] = v.strip().strip("'\"")
+        return res
+
+
+def resolve_from_args(args: argparse.Namespace) -> ProfileConfig:
+    """Credentials for one command, from its parsed common options."""
+    return ConfigManager().resolve_profile(args.profile, args.host, args.public_key, args.secret_key, args.env_file)

langfuse_cli/formatters/__init__.py

@@ -0,0 +1,15 @@
+"""Formatters for human terminal and agent-compact views."""
+import re
+
+_CONTROL_CHARS = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f\ud800-\udfff]")
+
+
+def clean(text: str) -> str:
+    """Escape terminal control characters (except newline and tab) and lone UTF-16 surrogates.
+
+    Trace names, inputs and error messages come from end users of the traced app; printed raw,
+    an escape sequence in them could rewrite the terminal. A lone surrogate (text cut inside an
+    emoji) cannot be encoded as UTF-8 at all.
+    """
+    # \uXXXX rather than \xXX: it is also a valid JSON escape, so JSON output stays parseable and lossless.
+    return _CONTROL_CHARS.sub(lambda m: f"\\u{ord(m.group()):04x}", text)

langfuse_cli/formatters/agent.py

@@ -0,0 +1,95 @@
+"""Token-efficient output formatters for AI coding assistants."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import tempfile
+from typing import Any, Dict, List, Optional
+
+from langfuse_cli.formatters import clean
+
+SUMMARY_THRESHOLD_BYTES = 16 * 1024
+SUMMARY_HINT = ("The JSON output is larger than 16 KB, so it was written to outputFile. Read only the parts you need, "
+                "for example with jq, or narrow the command with --agent-fields.")
+
+
+def extract_field_path(data: Any, path: str) -> Any:
+    """Value at a dotted path like 'usageDetails.input'; a list on the way maps the rest over its items."""
+    if isinstance(data, list):
+        return [extract_field_path(item, path) for item in data]
+    if not isinstance(data, dict):
+        return None
+    head, _, rest = path.partition(".")
+    value = data.get(head)
+    return extract_field_path(value, rest) if rest else value
+
+
+def filter_dict_fields(item: Dict[str, Any], fields: List[str]) -> Dict[str, Any]:
+    out: Dict[str, Any] = {}
+    for f in fields:
+        val = extract_field_path(item, f)
+        if val is not None:
+            out[f] = val
+    return out
+
+
+def prune(data: Any) -> Any:
+    """Drop None, "", [] and {} values at every level; this is what --compact does."""
+    empty = (None, "", [], {})
+    if isinstance(data, dict):
+        pruned = {k: prune(v) for k, v in data.items()}
+        return {k: v for k, v in pruned.items() if v not in empty}
+    if isinstance(data, list):
+        return [v for v in map(prune, data) if v not in empty]
+    return data
+
+
+def format_agent_output(
+    data: Any,
+    compact: bool = False,
+    agent_fields: Optional[str] = None,
+    summary: bool = False,
+) -> str:
+    """JSON for agents: optional field projection (applied to each list item), then optional pruning.
+
+    With `summary`, output over SUMMARY_THRESHOLD_BYTES goes to a file and a short envelope is returned instead.
+    """
+    if agent_fields:
+        fields = [f.strip() for f in agent_fields.split(",") if f.strip()]
+        if isinstance(data, list):
+            data = [filter_dict_fields(d, fields) for d in data if isinstance(d, dict)]
+        elif isinstance(data, dict):
+            data = filter_dict_fields(data, fields)
+    if compact:
+        # Prune inside each row but keep the rows: dropping emptied rows would print [] for real results.
+        data = [prune(row) for row in data] if isinstance(data, list) else prune(data)
+    text = json.dumps(data, indent=2, ensure_ascii=False)
+    if summary and len(text.encode("utf-8", "surrogatepass")) > SUMMARY_THRESHOLD_BYTES:
+        return json.dumps(_write_summary(data, text), indent=2)
+    return text
+
+
+def _write_summary(data: Any, text: str) -> Dict[str, Any]:
+    """Write `text` to a new private file and describe it."""
+    content = (clean(text) + "\n").encode("utf-8")  # the file gets the same escaping as the terminal
+    fd, path = tempfile.mkstemp(prefix="lf-", suffix=".json")  # mode 0600; kept, the caller reads it after lf exits
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(content)
+    except BaseException:
+        os.unlink(path)  # no half-written file left behind
+        raise
+    envelope: Dict[str, Any] = {"summary": True, "outputFile": path, "bytes": len(content)}
+    if isinstance(data, list):
+        envelope["rows"] = len(data)
+        envelope["rowKeys"] = list(dict.fromkeys(k for row in data if isinstance(row, dict) for k in row))
+    elif isinstance(data, dict):
+        envelope["keys"] = list(data)
+    envelope["hint"] = SUMMARY_HINT
+    return envelope
+
+
+def print_json(args: argparse.Namespace, data: Any) -> None:
+    """Print a data command's JSON result, honouring --agent-fields, --compact and --output-summary."""
+    print(format_agent_output(data, compact=args.compact, agent_fields=args.agent_fields, summary=args.output_summary))