The agent that turns websites into APIs!
feat: agent-friendly CLI surface
Kalil Bouzigues51680c9fc085
diff --git a/README.md b/README.mdindex 99db5ea..c65e249 100644--- a/README.md+++ b/README.md@@ -356,6 +356,42 @@ Use these slash commands while in the CLI:- `/help` - Show all commands- `/exit` - Quit+### Scripted / Agent Usage++The CLI subcommands are scriptable. Pass `--no-interactive` (and/or `--json`) so they fail fast instead of opening prompts, and pipe the structured output into `jq` or another agent.++```bash+# Run an autonomous agent capture and get a single JSON result on stdout+reverse-api-engineer agent \+ --prompt "capture the public jobs api" \+ --url https://example.com/jobs \+ --json | jq++# Output (logs go to stderr; one JSON object on stdout):+# {+# "schema_version": 1,+# "status": "ok",+# "run_id": "deadbeef0001",+# "prompt": "capture the public jobs api",+# "url": "https://example.com/jobs",+# "mode": "auto",+# "har_path": "/.../recording.har",+# "script_path": "/.../api_client.py",+# "usage": { ... },+# "error": null+# }++# List runs / inspect a run as JSON (empty history -> [])+reverse-api-engineer list --json+reverse-api-engineer show <run_id> --json++# Run a generated script non-interactively (errors on multiple-script picker+# or missing-dep prompt instead of blocking)+reverse-api-engineer run <run_id> --no-interactive --auto-install -- --org acme+```++Exit codes: `0` success, `1` runtime error, `2` misuse (missing required args).+## 🔌 Claude Code PluginInstall the plugin in [Claude Code](https://claude.com/claude-code):diff --git a/src/reverse_api/cli.py b/src/reverse_api/cli.pyindex 8c6f32d..831515a 100644--- a/src/reverse_api/cli.py+++ b/src/reverse_api/cli.py@@ -2,6 +2,8 @@ import asyncioimport jsonimport randomimport re+import sys+from contextlib import contextmanagerfrom pathlib import Pathimport click@@ -59,6 +61,66 @@ console = Console()config_manager = ConfigManager(get_config_path())session_manager = SessionManager(get_history_path())+# Stable schema version for --json outputs consumed by other agents/scripts.+AGENT_JSON_SCHEMA_VERSION = 1+++@contextmanager+def _quiet_consoles_for_json():+ """Reserve stdout for the final JSON payload; route Rich output to stderr.++ Yields the original stdout file object so the caller can write JSON to it+ after the wrapped block exits cleanly. Rich Console.file is a property that+ lazily resolves to sys.stdout, so we save/restore the underlying _file slot+ rather than the resolved file object.+ """+ real_stdout = sys.stdout+ redirected_consoles: list[tuple[Console, object]] = []+ sys.stdout = sys.stderr+ for mod_name, mod in list(sys.modules.items()):+ if not mod_name.startswith("reverse_api") or mod is None:+ continue+ candidate = getattr(mod, "console", None)+ if isinstance(candidate, Console):+ redirected_consoles.append((candidate, candidate._file))+ candidate.file = sys.stderr+ try:+ yield real_stdout+ finally:+ sys.stdout = real_stdout+ for c, original_inner in redirected_consoles:+ c._file = original_inner+++def _build_agent_payload(+ result: dict | None,+ *,+ prompt: str | None,+ url: str | None,+ error: str | None = None,+) -> dict:+ """Normalize an agent capture result into a stable JSON shape."""+ result = result or {}+ run_id = result.get("run_id")+ inner_error = result.get("error")+ final_error = error or inner_error or (None if run_id else "agent capture produced no run")+ har_path = None+ if run_id:+ candidate = get_har_dir(run_id, None) / "recording.har"+ har_path = str(candidate) if candidate.exists() else None+ return {+ "schema_version": AGENT_JSON_SCHEMA_VERSION,+ "status": "error" if final_error else "ok",+ "run_id": run_id,+ "prompt": prompt,+ "url": url,+ "mode": result.get("mode"),+ "har_path": har_path,+ "script_path": result.get("script_path"),+ "usage": result.get("usage") or {},+ "error": final_error,+ }+# Mode definitionsMODES = ["agent", "manual", "engineer", "collector"]MODE_DESCRIPTIONS = {@@ -1261,9 +1323,55 @@ def manual(prompt, url, reverse_engineer, model, output_dir):default=None,)@click.option("--output-dir", "-o", default=None, help="Custom output directory.")-def agent(prompt, url, reverse_engineer, model, output_dir):+ "--no-interactive",+ is_flag=True,+ help="Fail fast instead of prompting for missing inputs (intended for scripted/agent usage).",+)+ "--json",+ "as_json",+ is_flag=True,+ help="Emit a single JSON result on stdout (logs go to stderr). Implies --no-interactive.",+)+def agent(prompt, url, reverse_engineer, model, output_dir, no_interactive, as_json):"""Run autonomous agent browser session."""- run_agent_capture(prompt=prompt, url=url, reverse_engineer=reverse_engineer, model=model, output_dir=output_dir)+ no_interactive = no_interactive or as_json++ if no_interactive and not (prompt and prompt.strip()):+ if as_json:+ click.echo(json.dumps({+ "schema_version": AGENT_JSON_SCHEMA_VERSION,+ "status": "error",+ "error": "--prompt is required in non-interactive/--json mode",+ }))+ else:+ click.echo("error: --prompt is required when --no-interactive is set", err=True)+ sys.exit(2)++ if not as_json:+ run_agent_capture(prompt=prompt, url=url, reverse_engineer=reverse_engineer, model=model, output_dir=output_dir)+ return++ payload: dict+ with _quiet_consoles_for_json() as real_stdout:+ try:+ result = run_agent_capture(+ prompt=prompt,+ url=url,+ reverse_engineer=reverse_engineer,+ model=model,+ output_dir=output_dir,+ )+ payload = _build_agent_payload(result, prompt=prompt, url=url)+ except KeyboardInterrupt:+ payload = _build_agent_payload({}, prompt=prompt, url=url, error="interrupted")+ except Exception as e:+ payload = _build_agent_payload({}, prompt=prompt, url=url, error=str(e))++ real_stdout.write(json.dumps(payload) + "\n")+ real_stdout.flush()+ sys.exit(0 if payload["status"] == "ok" else 1)def run_manual_capture(prompt=None, url=None, reverse_engineer=True, model=None, output_dir=None):@@ -1637,7 +1745,12 @@ def run_auto_capture(prompt=None, url=None, model=None, output_dir=None, agent_ppaths={"script_path": result.get("script_path")},)- return result+ return {+ "run_id": run_id,+ "mode": mode_label,+ "script_path": (result or {}).get("script_path"),+ "usage": (result or {}).get("usage", {}),+ }except Exception as e:console.print(f" [red]auto mode error: {e}[/red]")@@ -1645,7 +1758,13 @@ def run_auto_capture(prompt=None, url=None, model=None, output_dir=None, agent_pimport tracebacktraceback.print_exc()- return None+ return {+ "run_id": run_id,+ "mode": mode_label,+ "script_path": None,+ "usage": {},+ "error": str(e),+ }def run_playwright_codegen(run_id: str, prompt: str, output_dir: str | None = None, start_url: str | None = None):@@ -1897,7 +2016,9 @@ def list_runs(as_json, full, limit, mode, model, search):runs = [r for r in runs if search.lower() in (r.get("prompt") or "").lower()]if not runs:- if not session_manager.history:+ if as_json:+ click.echo(json.dumps([]))+ elif not session_manager.history:console.print("No runs found.", style="dim")else:console.print("No matching runs found.")@@ -1968,10 +2089,16 @@ def show_run(run_id, as_json):elif session_manager.history:run = session_manager.history[0]else:+ if as_json:+ click.echo(json.dumps({"error": "no runs found"}))+ sys.exit(1)console.print("No runs found.", style="dim")returnif run is None:+ if as_json:+ click.echo(json.dumps({"error": "run not found", "run_id": run_id}))+ sys.exit(1)console.print(f"Run not found: {run_id}")return@@ -2066,8 +2193,18 @@ def show_run(run_id, as_json):@click.argument("script_args", nargs=-1, type=click.UNPROCESSED)@click.option("--file", "-f", "file_name", default=None, help="Script filename to run (e.g. api_client.py).")@click.option("--ls", "list_scripts", is_flag=True, help="List available scripts without executing.")+ "--no-interactive",+ is_flag=True,+ help="Fail fast on script-picker / missing-dependency prompts (intended for scripted/agent usage).",+)+ "--auto-install",+ is_flag=True,+ help="Auto-install missing dependencies on retry without prompting (implies --no-interactive for the picker).",+)@click.pass_context-def run_script(ctx, identifier, script_args, file_name, list_scripts):+def run_script(ctx, identifier, script_args, file_name, list_scripts, no_interactive, auto_install):"""Run a generated script from a previous run.IDENTIFIER is a run ID or search term to match against prompts.@@ -2132,6 +2269,11 @@ def run_script(ctx, identifier, script_args, file_name, list_scripts):script = matching[0]elif len(scripts) == 1:script = scripts[0]+ elif no_interactive or auto_install:+ available = ", ".join(s.name for s in scripts)+ raise click.ClickException(+ f"multiple scripts found for run {run_id}; pass --file <name> to choose. Available: {available}"+ )else:# Interactive pickerchoices = [questionary.Choice(title=s.name, value=s) for s in scripts]@@ -2181,9 +2323,14 @@ def run_script(ctx, identifier, script_args, file_name, list_scripts):missing = match.group(1).split(".")[0]console.print(f"[yellow]Missing dependency: {missing}[/yellow]")- install = questionary.confirm(- f"Install '{missing}' and retry?", default=True- ).ask()+ if auto_install:+ install = True+ elif no_interactive:+ install = False+ else:+ install = questionary.confirm(+ f"Install '{missing}' and retry?", default=True+ ).ask()if install:subprocess.run([str(venv_pip), "install", "-q", missing], check=True)console.print(f"Installed [green]{missing}[/green]. Retrying...")diff --git a/tests/test_cli_agent_json.py b/tests/test_cli_agent_json.pynew file mode 100644index 0000000..f8dca12--- /dev/null+++ b/tests/test_cli_agent_json.py@@ -0,0 +1,138 @@+"""Tests for the agent-friendly CLI surface (--json, --no-interactive, payload shape)."""++import json+from unittest.mock import patch++from click.testing import CliRunner++from reverse_api.cli import (+ AGENT_JSON_SCHEMA_VERSION,+ _build_agent_payload,+ agent,+ list_runs,+ show_run,+)+++class TestBuildAgentPayload:+ """Stable shape for the `agent --json` payload."""++ def test_success_shape(self, tmp_path):+ payload = _build_agent_payload(+ {+ "run_id": "abc123",+ "mode": "auto",+ "script_path": str(tmp_path / "scripts" / "api_client.py"),+ "usage": {"input_tokens": 1, "output_tokens": 2, "total_cost": 0.001},+ },+ prompt="capture the X api",+ url="https://example.com",+ )+ assert payload["schema_version"] == AGENT_JSON_SCHEMA_VERSION+ # No run produced a HAR yet on disk in this test, so har_path is None+ assert payload["status"] == "ok"+ assert payload["run_id"] == "abc123"+ assert payload["mode"] == "auto"+ assert payload["prompt"] == "capture the X api"+ assert payload["url"] == "https://example.com"+ assert payload["usage"]["total_cost"] == 0.001+ assert payload["error"] is None+ # Must be JSON-serializable (no Path objects sneaking through)+ json.dumps(payload)++ def test_no_run_id_is_error(self):+ payload = _build_agent_payload({}, prompt="x", url=None)+ assert payload["status"] == "error"+ assert payload["error"]+ assert payload["run_id"] is None++ def test_explicit_error_overrides(self):+ payload = _build_agent_payload(+ {"run_id": "abc", "mode": "auto"},+ prompt="x",+ url=None,+ error="boom",+ )+ assert payload["status"] == "error"+ assert payload["error"] == "boom"++ def test_inner_error_propagates(self):+ payload = _build_agent_payload(+ {"run_id": "abc", "mode": "auto", "error": "inner"},+ prompt="x",+ url=None,+ )+ assert payload["status"] == "error"+ assert payload["error"] == "inner"+++class TestAgentCommandJson:+ """`agent` click command's --json / --no-interactive behavior."""++ def test_json_without_prompt_exits_2(self):+ runner = CliRunner()+ result = runner.invoke(agent, ["--json"])+ assert result.exit_code == 2+ payload = json.loads(result.stdout.strip())+ assert payload["status"] == "error"+ assert "prompt" in payload["error"].lower()++ def test_no_interactive_without_prompt_exits_2(self):+ runner = CliRunner()+ result = runner.invoke(agent, ["--no-interactive"])+ assert result.exit_code == 2+ # Plain text on stderr, not JSON, since --json wasn't requested+ assert "prompt" in (result.stderr or result.output).lower()++ def test_json_emits_payload_on_success(self):+ runner = CliRunner()+ fake_result = {+ "run_id": "deadbeef0001",+ "mode": "auto",+ "script_path": None,+ "usage": {"total_cost": 0.0},+ }+ with patch("reverse_api.cli.run_agent_capture", return_value=fake_result):+ result = runner.invoke(agent, ["--json", "-p", "capture the X api"])+ assert result.exit_code == 0, result.output+ payload = json.loads(result.stdout.strip().splitlines()[-1])+ assert payload["status"] == "ok"+ assert payload["run_id"] == "deadbeef0001"+ assert payload["prompt"] == "capture the X api"++ def test_json_emits_error_payload_on_exception(self):+ runner = CliRunner()+ with patch("reverse_api.cli.run_agent_capture", side_effect=RuntimeError("boom")):+ result = runner.invoke(agent, ["--json", "-p", "x"])+ assert result.exit_code == 1+ payload = json.loads(result.stdout.strip().splitlines()[-1])+ assert payload["status"] == "error"+ assert payload["error"] == "boom"+++class TestListJsonEmpty:+ """`list --json` should emit a JSON array even when there is no history."""++ def test_empty_history_emits_empty_array(self, tmp_path):+ runner = CliRunner()+ # Repoint session_manager.history to empty list for the test+ with patch("reverse_api.cli.session_manager") as sm:+ sm.history = []+ result = runner.invoke(list_runs, ["--json"])+ assert result.exit_code == 0+ assert json.loads(result.stdout.strip()) == []+++class TestShowJsonNotFound:+ """`show <id> --json` should emit a structured error and exit non-zero."""++ def test_unknown_run_id_emits_error(self):+ runner = CliRunner()+ with patch("reverse_api.cli.session_manager") as sm:+ sm.get_run.return_value = None+ sm.history = []+ result = runner.invoke(show_run, ["doesnotexist", "--json"])+ assert result.exit_code == 1+ payload = json.loads(result.stdout.strip())+ assert "error" in payload+ assert payload["run_id"] == "doesnotexist"