langsmith-cli 0.3.2__tar.gz → 0.3.4__tar.gz

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith-cli",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "A context-efficient interface for LangSmith observability and evaluations.",
   "author": {
     "name": "Aviad Rozenhek",

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/CLAUDE.md

@@ -111,10 +111,18 @@ main.py (entry point)
 ├── runs (group)
 │   ├── list
 │   ├── get
+│   ├── get-latest
 │   ├── stats
 │   ├── open
 │   ├── watch
-│   └── search
+│   ├── search
+│   ├── sample
+│   ├── analyze
+│   ├── tags
+│   ├── metadata-keys
+│   ├── fields
+│   ├── describe
+│   └── view-file
 ├── datasets (group)
 │   ├── list
 │   ├── get
@@ -124,10 +132,13 @@ main.py (entry point)
 │   ├── list
 │   ├── get
 │   └── create
-└── prompts (group)
-    ├── list
-    ├── get
-    └── push
+├── prompts (group)
+│   ├── list
+│   ├── get
+│   └── push
+└── self (group)
+    ├── detect
+    └── update
 ```
 
 ### Key Design Patterns
@@ -217,23 +228,37 @@ def list_runs(ctx, output_format, count, output, ...):
 ```
 src/langsmith_cli/
 ├── __init__.py
-├── main.py              # Entry point, CLI group registration
-├── logging.py           # CLILogger for verbosity control and stream separation
+├── main.py              # Entry point, CLI group registration, global error handler
+├── cli_logging.py       # CLILogger for verbosity control and stream separation
+├── config.py            # Credentials file management
+├── field_analysis.py    # Field discovery and statistics (runs fields/describe)
+├── filters.py           # FQL filter builders and time parsing
+├── utils.py             # Shared helpers (output formatting, project resolution, etc.)
 └── commands/            # Modular command implementations
     ├── auth.py          # Authentication (login)
     ├── projects.py      # Project management
     ├── runs.py          # Runs/traces (largest module)
     ├── datasets.py      # Dataset operations
     ├── examples.py      # Dataset examples
-    └── prompts.py       # Prompt management
+    ├── prompts.py       # Prompt management
+    └── self_cmd.py      # Self-inspection (detect, update)
 
 tests/
-├── conftest.py          # Pytest fixtures (CliRunner)
-├── test_main.py         # Root CLI tests
+├── conftest.py          # Pytest fixtures (CliRunner, model factories)
+├── test_main.py         # Root CLI + global error handler tests
 ├── test_logging.py      # CLILogger tests
 ├── test_auth.py         # Auth command tests
 ├── test_projects.py     # Projects command tests
-├── test_runs.py         # Runs command tests (largest)
+├── test_runs.py         # Runs command tests
+├── test_runs_list.py    # Runs list command tests (filters, JSON, formats)
+├── test_runs_get.py     # Runs get/get-latest/open tests
+├── test_runs_roots.py   # Runs --roots flag tests
+├── test_runs_sample.py  # Runs sample command tests
+├── test_datasets.py     # Datasets command tests
+├── test_examples.py     # Examples command tests
+├── test_prompts.py      # Prompts command tests
+├── test_self.py         # Self detect/update command tests
+├── test_utils.py        # Utility function tests
 ├── test_smoke.py        # Smoke tests (requires API key)
 └── test_e2e.py          # End-to-end tests (requires API key)
 

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langsmith-cli
-Version: 0.3.2
+Version: 0.3.4
 Summary: Context-efficient CLI for LangSmith. Built for humans and agents.
 Project-URL: Homepage, https://github.com/aviadr1/langsmith-cli
 Project-URL: Repository, https://github.com/aviadr1/langsmith-cli
@@ -158,10 +158,11 @@ langsmith-cli runs watch
 ### 📦 **Complete Coverage**
 Every LangSmith resource at your fingertips:
 - ✅ **Projects** - List, create, inspect
-- ✅ **Runs** - Search, stats, watch, open in browser
+- ✅ **Runs** - Search, stats, watch, sample, analyze, field discovery
 - ✅ **Datasets** - CRUD + bulk JSONL uploads
 - ✅ **Examples** - Full lifecycle management
 - ✅ **Prompts** - Version control your prompts
+- ✅ **Self** - Installation detection + auto-update
 
 ---
 
@@ -310,8 +311,8 @@ langsmith-cli runs watch --project production
 ### 💾 Bulk Dataset Uploads
 
 ```bash
-# Export examples to JSONL
-langsmith-cli --json examples list --dataset my-dataset > examples.jsonl
+# Export examples to JSONL (using --output for reliable file writing)
+langsmith-cli examples list --dataset my-dataset --output examples.jsonl
 
 # Upload to new dataset
 langsmith-cli datasets push examples.jsonl --dataset production-eval
@@ -424,9 +425,18 @@ auth login              # Authenticate with LangSmith
 projects list           # List all projects
 runs list              # Search and filter runs
 runs get <id>          # Inspect a specific run
+runs get-latest        # Get most recent run matching filters
 runs stats             # Aggregate statistics
 runs watch             # Live run dashboard
 runs open <id>         # Open trace in browser
+runs search            # Full-text search across runs
+runs sample            # Stratified sampling by tags/metadata
+runs analyze           # Group runs and compute metrics
+runs tags              # Discover tag patterns
+runs metadata-keys     # Discover metadata keys
+runs fields            # Discover field paths and types
+runs describe          # Detailed field statistics
+runs view-file         # View runs from JSONL files
 datasets list          # List datasets
 datasets create        # Create new dataset
 datasets push          # Bulk upload from JSONL
@@ -435,6 +445,8 @@ examples create        # Add example to dataset
 prompts list           # List prompt repositories
 prompts get            # Pull a prompt template
 prompts push           # Push local prompt to LangSmith
+self detect            # Show installation details
+self update            # Update to latest version
 ```
 
 ### Global Flags
@@ -450,7 +462,8 @@ prompts push           # Push local prompt to LangSmith
 
 | Option | Description | Example |
 |--------|-------------|---------|
-| `--project` | Filter by project | `--project production` |
+| `--project` | Filter by project name | `--project production` |
+| `--project-id` | Filter by project UUID | `--project-id abc-123...` |
 | `--status` | Filter by status | `--status error` |
 | `--failed` | Only failed runs | `--failed` |
 | `--succeeded` | Only successful runs | `--succeeded` |
@@ -542,8 +555,7 @@ uv run pyright
 ```
 
 ### Project Stats
-- **79% Test Coverage** (116 tests)
-- **100% Utils Coverage** (47 tests for helpers)
+- **92% Test Coverage** (589 tests)
 - **Zero Type Errors** (Pyright clean)
 - **100% MCP Parity** (13/13 tools)
 

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/README.md

@@ -108,10 +108,11 @@ langsmith-cli runs watch
 ### 📦 **Complete Coverage**
 Every LangSmith resource at your fingertips:
 - ✅ **Projects** - List, create, inspect
-- ✅ **Runs** - Search, stats, watch, open in browser
+- ✅ **Runs** - Search, stats, watch, sample, analyze, field discovery
 - ✅ **Datasets** - CRUD + bulk JSONL uploads
 - ✅ **Examples** - Full lifecycle management
 - ✅ **Prompts** - Version control your prompts
+- ✅ **Self** - Installation detection + auto-update
 
 ---
 
@@ -260,8 +261,8 @@ langsmith-cli runs watch --project production
 ### 💾 Bulk Dataset Uploads
 
 ```bash
-# Export examples to JSONL
-langsmith-cli --json examples list --dataset my-dataset > examples.jsonl
+# Export examples to JSONL (using --output for reliable file writing)
+langsmith-cli examples list --dataset my-dataset --output examples.jsonl
 
 # Upload to new dataset
 langsmith-cli datasets push examples.jsonl --dataset production-eval
@@ -374,9 +375,18 @@ auth login              # Authenticate with LangSmith
 projects list           # List all projects
 runs list              # Search and filter runs
 runs get <id>          # Inspect a specific run
+runs get-latest        # Get most recent run matching filters
 runs stats             # Aggregate statistics
 runs watch             # Live run dashboard
 runs open <id>         # Open trace in browser
+runs search            # Full-text search across runs
+runs sample            # Stratified sampling by tags/metadata
+runs analyze           # Group runs and compute metrics
+runs tags              # Discover tag patterns
+runs metadata-keys     # Discover metadata keys
+runs fields            # Discover field paths and types
+runs describe          # Detailed field statistics
+runs view-file         # View runs from JSONL files
 datasets list          # List datasets
 datasets create        # Create new dataset
 datasets push          # Bulk upload from JSONL
@@ -385,6 +395,8 @@ examples create        # Add example to dataset
 prompts list           # List prompt repositories
 prompts get            # Pull a prompt template
 prompts push           # Push local prompt to LangSmith
+self detect            # Show installation details
+self update            # Update to latest version
 ```
 
 ### Global Flags
@@ -400,7 +412,8 @@ prompts push           # Push local prompt to LangSmith
 
 | Option | Description | Example |
 |--------|-------------|---------|
-| `--project` | Filter by project | `--project production` |
+| `--project` | Filter by project name | `--project production` |
+| `--project-id` | Filter by project UUID | `--project-id abc-123...` |
 | `--status` | Filter by status | `--status error` |
 | `--failed` | Only failed runs | `--failed` |
 | `--succeeded` | Only successful runs | `--succeeded` |
@@ -492,8 +505,7 @@ uv run pyright
 ```
 
 ### Project Stats
-- **79% Test Coverage** (116 tests)
-- **100% Utils Coverage** (47 tests for helpers)
+- **92% Test Coverage** (589 tests)
 - **Zero Type Errors** (Pyright clean)
 - **100% MCP Parity** (13/13 tools)
 

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/docs/QOL_IMPROVEMENTS.md

@@ -183,7 +183,6 @@ presets:
       project: production
       status: error
       limit: 50
-      order-by: "-start_time"
 
   expensive-llm-calls:
     command: runs list

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/docs/dev/MCP_PARITY.md

@@ -45,7 +45,6 @@ This document tracks feature parity between the langsmith-cli and the official L
 - ✅ `is_root` → `--is-root`
 - ✅ `trace_filter` → `--trace-filter`
 - ✅ `tree_filter` → `--tree-filter`
-- ✅ `order_by` → `--order-by`
 - ✅ `reference_example_id` → `--reference-example-id`
 
 **`runs get`** (2/2 parameters):

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "langsmith-cli"
 # IMPORTANT: When bumping this version, also update .claude-plugin/plugin.json
-version = "0.3.2"
+version = "0.3.4"
 description = "Context-efficient CLI for LangSmith. Built for humans and agents."
 readme = "README.md"
 requires-python = ">=3.12"

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/skills/langsmith/SKILL.md

@@ -48,8 +48,8 @@ langsmith-cli runs list --project my-project --fields id,name,status --output ru
 ```bash
 # ❌ WRONG - Never use shell redirection for data extraction
 langsmith-cli --json runs list --project my-project > runs.json
-# If API fails: you get empty [], no error message, exit code 0
-# You won't know anything went wrong!
+# If API fails: errors go to stderr (invisible with redirection)
+# You may get a JSON error object instead of data, and won't know what happened
 ```
 
 ```bash
@@ -107,7 +107,8 @@ langsmith-cli --json runs list --project my-project --limit 5 2>&1
 
 ### Runs (Traces)
 - `langsmith-cli --json runs list [OPTIONS]`: List recent runs.
-  - `--project <name>`: Filter by project.
+  - `--project <name>`: Filter by project name (default: "default").
+  - `--project-id <uuid>`: Filter by project UUID (bypasses name resolution, faster).
   - `--limit <n>`: Max results (default 10, keep it small).
   - `--status <success|error>`: Filter by status.
   - `--filter <string>`: Advanced FQL query string (see FQL examples below).
@@ -211,6 +212,13 @@ langsmith-cli --json runs list --project my-project --limit 5 2>&1
 - `langsmith-cli --json prompts get <name> [--commit <hash>]`: Fetch a prompt template.
 - `langsmith-cli --json prompts push <name> <file_path>`: Push a local file as a prompt.
 
+### Self (Installation Management)
+- `langsmith-cli self detect`: Show installation details (version, install method, paths).
+  - Reports: version, install method (uv tool, pipx, pip, editable), install path, executable path, Python version.
+- `langsmith-cli self update`: Update langsmith-cli to the latest version.
+  - Auto-detects install method and runs the appropriate upgrade command.
+  - Checks PyPI for latest version before updating.
+
 ## Common Patterns (No Piping Needed)
 
 The CLI provides built-in commands that eliminate the need for Unix pipes, jq, and nested commands:

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/skills/langsmith/docs/examples.md

@@ -23,8 +23,7 @@ This document provides practical workflows and use cases for common LangSmith op
 langsmith-cli --json runs list \
   --project production-app \
   --status error \
-  --limit 5 \
-  --order-by -start_time
+  --limit 5
 
 # Step 2: Inspect specific failure (context-efficient)
 langsmith-cli --json runs get <run-id> \
@@ -75,8 +74,7 @@ langsmith-cli runs open <trace-id>
 langsmith-cli --json runs list \
   --project production-app \
   --filter 'gt(latency, "5s")' \
-  --limit 20 \
-  --order-by -latency
+  --limit 20
 
 # Step 2: Analyze latency distribution
 langsmith-cli --json runs stats \
@@ -374,8 +372,7 @@ langsmith-cli --json runs stats --project production-app --limit 1000
 langsmith-cli --json runs list \
   --project production-app \
   --filter 'gt(total_cost, 0.1)' \
-  --limit 20 \
-  --order-by -total_cost
+  --limit 20
 
 # Analyze cost by component type
 langsmith-cli --json runs list \
@@ -685,7 +682,6 @@ while true; do
     RUNS=$(langsmith-cli --json runs list \
       --project "$PROJECT" \
       --limit 100 \
-      --order-by -start_time \
       $FILTER)
 
     # Process each new run

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/skills/langsmith/references/runs.md

@@ -18,7 +18,6 @@ langsmith-cli --json runs list [OPTIONS]
 - `--filter TEXT` - Advanced FQL query (see Filter Query Language section)
 - `--trace-filter TEXT` - Filter applied to root run of trace
 - `--tree-filter TEXT` - Filter applied to any run in trace tree
-- `--order-by TEXT` - Sort field (default: `-start_time`). Prefix with `-` for descending
 - `--reference-example-id UUID` - Filter runs by reference example ID
 
 **Output Fields:**
@@ -194,4 +193,3 @@ langsmith-cli runs watch [OPTIONS]
 - `--refresh INTEGER` - Refresh interval in seconds (default: 2)
 
 **Behavior:** Shows live table of recent runs with auto-refresh
-

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/skills/langsmith/references/troubleshooting.md

@@ -80,8 +80,14 @@ langsmith-cli <command> [options]
 **Solution:** Run `langsmith-cli auth login` or set `LANGSMITH_API_KEY` env var
 
 ### "Project not found"
-**Cause:** Project name doesn't exist
-**Solution:** Run `langsmith-cli projects list` to see available projects
+**Cause:** Project name doesn't exist or has a path prefix (e.g., `prd/my-project`)
+**Solution:**
+1. The error message will suggest similar project names if available
+2. List projects: `langsmith-cli --json projects list --fields name`
+3. Use substring matching: `langsmith-cli --json runs list --project-name my-project`
+4. Use wildcards: `langsmith-cli --json runs list --project-name-pattern "*my-project*"`
+5. If you have a UUID, pass it to `--project-id` or `--project` (UUIDs are auto-detected)
+6. In JSON mode, the error includes structured `suggestions` and `failed_sources` fields
 
 ### "Dataset not found"
 **Cause:** Dataset name doesn't match exactly

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/src/langsmith_cli/commands/datasets.py

@@ -232,6 +232,17 @@ def push_dataset(ctx, file_path, dataset):
         dataset_name=dataset,
     )
 
-    logger.success(
-        f"Successfully pushed {len(examples)} examples to dataset '{dataset}'"
-    )
+    if ctx.obj.get("json"):
+        click.echo(
+            json_dumps(
+                {
+                    "status": "success",
+                    "dataset": dataset,
+                    "examples_count": len(examples),
+                }
+            )
+        )
+    else:
+        logger.success(
+            f"Successfully pushed {len(examples)} examples to dataset '{dataset}'"
+        )

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/src/langsmith_cli/commands/prompts.py

@@ -164,4 +164,9 @@ def push_prompt(ctx, name, file_path, description, tags, is_public):
         is_public=is_public,
     )
 
-    logger.success(f"Successfully pushed prompt to {name}")
+    if ctx.obj.get("json"):
+        from langsmith_cli.utils import json_dumps
+
+        click.echo(json_dumps({"status": "success", "name": name}))
+    else:
+        logger.success(f"Successfully pushed prompt to {name}")

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/src/langsmith_cli/commands/runs.py

@@ -25,11 +25,13 @@ from langsmith_cli.utils import (
     filter_fields,
     get_matching_items,
     get_or_create_client,
+    get_project_suggestions,
     json_dumps,
     output_formatted_data,
     output_option,
     output_single_item,
     parse_duration_to_seconds,
+    raise_if_all_failed_with_suggestions,
     render_run_details,
     resolve_project_filters,
     sort_items,
@@ -321,9 +323,6 @@ def compute_metrics(
 )
 @click.option("--trace-filter", help="Filter applied to root trace.")
 @click.option("--tree-filter", help="Filter if any run in trace tree matches.")
-@click.option(
-    "--order-by", default="-start_time", help="Sort field (prefix with - for desc)."
-)
 @click.option("--reference-example-id", help="Filter runs for a specific example.")
 @click.option(
     "--tag",
@@ -430,7 +429,6 @@ def list_runs(
     roots,
     trace_filter,
     tree_filter,
-    order_by,
     reference_example_id,
     tag,
     name_pattern,
@@ -661,7 +659,6 @@ def list_runs(
         is_root=is_root,
         trace_filter=trace_filter,
         tree_filter=tree_filter,
-        order_by=order_by,
         reference_example_id=reference_example_id,
         console=None,  # Don't auto-report warnings (we have custom diagnostics below)
     )
@@ -669,11 +666,10 @@ def list_runs(
     failed_projects = result.failed_sources
 
     # CRITICAL: Fail fast if ALL sources failed (prevents silent failures)
-    # In JSON mode, output empty array before failing for parseable output
-    if result.all_failed and (ctx.obj.get("json") or output_format in ["csv", "yaml"]):
-        format_type = determine_output_format(output_format, ctx.obj.get("json"))
-        output_formatted_data([], format_type)
-    result.raise_if_all_failed(logger, "runs")
+    # The global error handler in LangSmithCLIGroup outputs JSON errors in --json mode,
+    # so we don't need to output [] here (which would cause double output on stdout).
+    # Uses raise_if_all_failed_with_suggestions to suggest similar project names.
+    raise_if_all_failed_with_suggestions(result, client, pq, logger, "runs")
 
     # Report partial failures (some succeeded, some failed)
     if result.has_failures:
@@ -993,7 +989,6 @@ def get_latest_run(
         error=error_filter,
         filter=combined_filter,
         is_root=roots,
-        order_by="-start_time",
     )
 
     if pq.use_id:
@@ -1028,6 +1023,16 @@ def get_latest_run(
             if len(failed_projects) > 3:
                 logger.warning(f"  • ... and {len(failed_projects) - 3} more")
 
+            # Suggest similar project names for single-project failures
+            failed_names = [
+                name for name, _ in failed_projects if not name.startswith("id:")
+            ]
+            if len(failed_names) == 1:
+                suggestions = get_project_suggestions(client, failed_names[0])
+                if suggestions:
+                    suggestion_list = ", ".join(f"'{s}'" for s in suggestions[:5])
+                    logger.info(f"Did you mean: {suggestion_list}?")
+
         raise click.Abort()
 
     data = filter_fields(latest_run, fields)
@@ -1168,7 +1173,14 @@ def run_stats(
                 resolved_project_ids.append(proj_name)
 
     if not resolved_project_ids:
-        console.print("[yellow]No matching projects found.[/yellow]")
+        if ctx.obj.get("json"):
+            click.echo(
+                json_dumps(
+                    {"error": "NotFoundError", "message": "No matching projects found."}
+                )
+            )
+        else:
+            console.print("[yellow]No matching projects found.[/yellow]")
         return
 
     stats = client.get_run_stats(project_ids=resolved_project_ids)
@@ -1206,8 +1218,11 @@ def open_run(ctx, run_id):
     # The SDK also has a way to get the URL but it might require project name.
     url = f"https://smith.langchain.com/r/{run_id}"
 
-    click.echo(f"Opening run {run_id} in browser...")
-    click.echo(f"URL: {url}")
+    if ctx.obj.get("json"):
+        click.echo(json_dumps({"run_id": run_id, "url": url}))
+    else:
+        click.echo(f"Opening run {run_id} in browser...")
+        click.echo(f"URL: {url}")
     webbrowser.open(url)
 
 
@@ -1447,7 +1462,6 @@ def search_runs(
         roots=roots,  # Pass through --roots flag
         trace_filter=None,
         tree_filter=None,
-        order_by="-start_time",
         reference_example_id=None,
         tag=(),
         name_pattern=None,
@@ -1664,7 +1678,6 @@ def sample_runs(
                 project_query=pq,
                 limit=sample_limit,
                 filter=combined_filter,
-                order_by="-start_time",
                 console=console,
             )
             stratum_runs = result.items[:sample_limit]
@@ -1713,7 +1726,6 @@ def sample_runs(
                 project_query=pq,
                 limit=samples_per_stratum,
                 filter=combined_filter,
-                order_by="-start_time",
                 console=console,
             )
             stratum_runs = result.items[:samples_per_stratum]
@@ -1954,7 +1966,6 @@ def analyze_runs(
             project_query=pq,
             filter=combined_filter,
             limit=None,
-            order_by="-start_time",
             console=console,
         )
         all_runs = result.items
@@ -1973,7 +1984,6 @@ def analyze_runs(
                     **proj_kwargs,
                     filter=combined_filter,
                     limit=None,  # SDK paginates automatically
-                    order_by="-start_time",
                     select=list(select_fields) if select_fields else None,
                 )
 
@@ -2142,7 +2152,6 @@ def _fetch_runs_for_discovery(
         _fetch_runs,
         project_query=pq,
         limit=sample_size,
-        order_by="-start_time",
         select=select,
         filter=combined_filter,
         console=console,

{langsmith_cli-0.3.2 → langsmith_cli-0.3.4}/src/langsmith_cli/main.py

@@ -1,6 +1,7 @@
 import sys
 import json as json_lib
 import os
+from typing import Any
 import click
 from rich.console import Console
 from dotenv import load_dotenv
@@ -147,8 +148,40 @@ class LangSmithCLIGroup(click.Group):
                     sys.exit(1)
 
             else:
-                # Unexpected error - re-raise for debugging
-                raise
+                # Non-LangSmith error (Click exceptions, Python exceptions, etc.)
+                from langsmith_cli.utils import CLIFetchError
+
+                if json_mode:
+                    # In JSON mode, ALWAYS output structured JSON to stdout.
+                    # Empty stdout breaks piped JSON parsing (json.loads fails).
+                    if isinstance(e, CLIFetchError):
+                        # Structured error with failure details and suggestions
+                        error_data: dict[str, Any] = {
+                            "error": "FetchError",
+                            "message": e.format_message(),
+                            "failed_sources": [
+                                {"name": n, "error": err} for n, err in e.failed_sources
+                            ],
+                            "suggestions": e.suggestions,
+                        }
+                        exit_code = e.exit_code
+                    elif isinstance(e, click.ClickException):
+                        error_data = {
+                            "error": type(e).__name__,
+                            "message": e.format_message(),
+                        }
+                        exit_code = e.exit_code
+                    else:
+                        error_data = {
+                            "error": type(e).__name__,
+                            "message": str(e),
+                        }
+                        exit_code = 1
+                    click.echo(json_lib.dumps(error_data))
+                    sys.exit(exit_code)
+                else:
+                    # In human mode, re-raise for Click's default formatting
+                    raise
         finally:
             # Flush stdout to prevent data loss when piping to other processes
             # This fixes race conditions where buffered output may not reach the pipe