Skip to content

The agent that turns websites into APIs!

fix(cli): expose agent tracebacks with RAE_DEBUG

kalil0321fabf52345178
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7c3cf2..fc37430 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **Live client validation**: an opt-in local test captures a fixture API, generates a Python or PowerShell client with a verified free OpenCode model, and checks fresh API data on replay. The manual `live_windows` CI option validates both languages using preinstalled Chrome and cached Python/npm dependencies, without downloading Chromium. Regular CI requires real PowerShell execution and CLI startup checks across all three operating systems.
### Fixed
+- Expose unexpected agent capture tracebacks through `RAE_DEBUG=1` on stderr, without adding diagnostics to JSON/NDJSON stdout.
- Keep the website header pinned to the viewport during rapid scrolling on the homepage and documentation pages, while preserving the content offset. Add browser regression coverage to the website deployment workflow.
- **PowerShell execution validation**: reject unsupported module names, missing `Example.ps1`, and script arguments that the example cannot forward, rather than silently running a different command. Generation instructions require portable module imports and terminating errors so failed API calls produce a nonzero exit status.
- Refresh the locked Claude Agent SDK and MCP dependencies so the development environment also uses MCP 2.x and `httpx2`, without the legacy `httpx`, `httpx-sse`, and `httpcore` packages. Add subprocess smoke tests for CLI startup with legacy HTTP client imports blocked.
diff --git a/README.md b/README.md
index a178a2c..c125740 100644
--- a/README.md
+++ b/README.md
@@ -169,6 +169,12 @@ Pass `--no-interactive` (and/or `--json`) to skip prompts. With `--json`, stdout
For `run`, the exit code is the underlying script's return code on success, `1` if no script was found, or non-zero if `--no-interactive` would have had to prompt.
+### Debugging agent failures
+
+Set the `RAE_DEBUG` environment variable to `1` to print the Python traceback
+for unexpected agent capture failures to stderr. Normal error messages remain
+concise by default, and `--json` / `--json-stream` stdout remains machine-readable.
+
## Output locations
- `~/.reverse-api/runs/scripts/{run_id}/`: permanent storage
diff --git a/src/reverse_api/cli.py b/src/reverse_api/cli.py
index 543312e..3191639 100644
--- a/src/reverse_api/cli.py
+++ b/src/reverse_api/cli.py
@@ -6,6 +6,7 @@ import logging
import os
import random
import sys
+import traceback
from collections.abc import Callable, Iterable, Iterator
from contextlib import contextmanager
from pathlib import Path
@@ -1028,6 +1029,7 @@ def main(ctx: click.Context, show_schema_version: bool) -> None:
Scripted flags are subcommand-specific: agent, engineer, and run support
--json, --json-stream, and --no-interactive; list/show support --json.
+ Set RAE_DEBUG=1 to include unexpected agent failure tracebacks on stderr.
See `<cmd> --help` for details. Wrappers that need to gate on the payload
schema can call `reverse-api-engineer
--json-schema-version`.
@@ -2276,7 +2278,10 @@ def run_auto_capture(
message = str(e) or type(e).__name__
click.echo(f"error: {message}", err=True)
click.echo(ERROR_CTA, err=True)
- logging.getLogger(__name__).debug("Auto mode failed", exc_info=True)
+ if os.environ.get("RAE_DEBUG") == "1":
+ traceback.print_exc(file=sys.stderr)
+ else:
+ logging.getLogger(__name__).debug("Auto mode failed", exc_info=True)
return {
"run_id": run_id,
"mode": mode_label,
diff --git a/tests/test_cli_agent_json.py b/tests/test_cli_agent_json.py
index 4c862f2..d8a0763 100644
--- a/tests/test_cli_agent_json.py
+++ b/tests/test_cli_agent_json.py
@@ -625,9 +625,11 @@ def test_provider_interrupt_output_modes(tmp_path, monkeypatch, sdk, output_flag
assert history[0]["paths"]["script_path"]
[email protected]("debug", [False, True])
@pytest.mark.parametrize("error_type", [Exception, TimeoutError])
@pytest.mark.parametrize("output_flag", [None, "--json", "--json-stream", "--no-interactive"])
-def test_empty_provider_exception_is_failure(tmp_path, error_type, output_flag):
+def test_empty_provider_exception_is_failure(tmp_path, monkeypatch, error_type, output_flag, debug):
+ monkeypatch.setenv("RAE_DEBUG", "1" if debug else "0")
from reverse_api.config import ConfigManager
config = ConfigManager(tmp_path / "config.json")
@@ -650,7 +652,10 @@ def test_empty_provider_exception_is_failure(tmp_path, error_type, output_flag):
assert payload["error"] == error_type.__name__
else:
assert result.stderr.count(f"error: {error_type.__name__}") == 1
- assert "Traceback" not in result.stderr
+ assert ("Traceback (most recent call last):" in result.stderr) is debug
+ assert "Traceback" not in result.stdout
+ if debug:
+ assert "run_auto_capture" in result.stderr
@pytest.mark.parametrize("output_flag", ["--json", "--json-stream", "--no-interactive"])