The agent that turns websites into APIs!
Fix scripted CLI modes and docs
kalil0321f1a64d37ca52
diff --git a/src/reverse_api/cli.py b/src/reverse_api/cli.pyindex f12c341..08a5c21 100644--- a/src/reverse_api/cli.py+++ b/src/reverse_api/cli.py@@ -493,6 +493,56 @@ def _build_engineer_payload("error_kind": error_kind,}++def _build_run_payload(+ *,+ identifier: str,+ run_id: str | None = None,+ script_path: str | None = None,+ script_args: tuple[str, ...] | list[str] = (),+ returncode: int | None = None,+ stdout: str | None = None,+ stderr: str | None = None,+ scripts: list[Path] | None = None,+ error: str | BaseException | None = None,+ error_kind_hint: str = "unknown",+) -> dict:+ """Normalize `run --json` output into a stable machine-readable shape."""+ error_str = _format_error_message(error)+ if error_str is None and returncode not in (None, 0):+ error_str = f"script exited with code {returncode}"+ error_kind = _classify_error(error, default=error_kind_hint) if error_str else None+ if error_str and error is None:+ error_kind = error_kind_hint+ return {+ "schema_version": AGENT_JSON_SCHEMA_VERSION,+ "status": "error" if error_str else "ok",+ "identifier": identifier,+ "run_id": run_id,+ "script_path": script_path,+ "script_args": list(script_args),+ "returncode": returncode,+ "stdout": stdout,+ "stderr": stderr,+ "scripts": [+ {+ "name": p.name,+ "path": str(p),+ "size": p.stat().st_size if p.exists() else None,+ "modified": p.stat().st_mtime if p.exists() else None,+ }+ for p in (scripts or [])+ ],+ "error": error_str,+ "error_kind": error_kind,+ }+++def _write_json_event(real_stdout, payload: dict) -> None:+ real_stdout.write(json.dumps(payload) + "\n")+ real_stdout.flush()++# Mode definitionsMODES = ["agent", "manual", "engineer", "collector"]MODE_DESCRIPTIONS = {@@ -774,11 +824,13 @@ def main(ctx: click.Context, show_schema_version: bool):"""reverse-api-engineer: reverse engineer apis.Run without a subcommand to start the interactive REPL; use agent, manual,- or engineer for CLI mode.+ engineer, or collector mode interactively.- Most subcommands accept --json and --no-interactive for scripted use; see- `<cmd> --help` for per-command details. Wrappers that need to gate on the- payload schema can call `reverse-api-engineer --json-schema-version`.+ Scripted flags are subcommand-specific: agent, engineer, and run support+ --json, --json-stream, and --no-interactive; list/show support --json.+ See `<cmd> --help` for details. Wrappers that need to gate on the payload+ schema can call `reverse-api-engineer+ --json-schema-version`."""if show_schema_version:click.echo(str(AGENT_JSON_SCHEMA_VERSION))@@ -1440,38 +1492,6 @@ def handle_messages(run_id: str, mode_color=THEME_PRIMARY):console.print()[email protected]("--prompt", "-p", default=None, help="Capture description.")[email protected]("--url", "-u", default=None, help="Starting URL.")- "--reverse-engineer/--no-engineer",- "reverse_engineer",- default=True,- help="Auto-run Claude.",-)- "--model",- "-m",- type=click.Choice(["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5"]),- default=None,-)[email protected]("--output-dir", "-o", default=None, help="Custom output directory.")-def manual(prompt, url, reverse_engineer, model, output_dir):- """Start a manual browser session.-- \b- Interactive only — this mode requires a human in front of a real,- visible browser to navigate, click, and submit forms. It cannot be- driven by an agent or run on a headless machine. There is no- --headless / --json / --no-interactive flag here on purpose.-- For scripted / agent / CI use cases, use `agent --json --headless`- instead, which runs an autonomous AI-driven capture without needing- a human or an X server.- """- run_manual_capture(prompt, url, reverse_engineer, model, output_dir)--@main.command(epilog="""\bExamples:@@ -1490,8 +1510,16 @@ JSON output schema (--json):"mode": "auto" | "chrome-mcp" | "agent-browser" | null,"har_path": "/abs/path/recording.har" | null,"script_path": "/abs/path/api_client.py" | null,- "usage": { "input_tokens": ..., "output_tokens": ..., "total_cost": ... },- "error": "<message>" | null+ "usage": {+ "input_tokens": ...,+ "output_tokens": ...,+ "cache_read_tokens": ...,+ "cache_write_tokens": ...,+ "total_cost_usd": ...,+ "raw": { ... }+ },+ "error": "<message>" | null,+ "error_kind": "misuse" | "config_invalid" | "permission_denied" | "network" | "engine_failure" | "interrupted" | "unknown" | null}\b@@ -1540,8 +1568,7 @@ Exit codes:def agent(prompt, url, model, output_dir, no_interactive, as_json, json_stream, headless, dry_run):"""Run autonomous agent browser session.- Agent mode runs an integrated capture + reverse-engineering pipeline; if you- only want a HAR recording, use `manual --no-engineer` instead.+ Agent mode runs an integrated capture + reverse-engineering pipeline."""if dry_run:# --dry-run is fundamentally about emitting machine-parseable validation@@ -1624,6 +1651,42 @@ def agent(prompt, url, model, output_dir, no_interactive, as_json, json_stream,sys.exit(0 if payload["status"] == "ok" else 1)+ epilog="""\b+Examples:+ reverse-api-engineer collector -p "collect companies hiring browser automation engineers"+ reverse-api-engineer collector+"""+)[email protected]("--prompt", "-p", default=None, help="Collection instructions.")+ "--model",+ "-m",+ type=click.Choice(["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5"]),+ default=None,+)[email protected]("--output-dir", "-o", default=None, help="Custom output directory for run metadata and messages.")+def collector(prompt, model, output_dir):+ """Run AI-powered data collection."""+ if prompt is None:+ if not sys.stdin.isatty():+ click.echo("error: --prompt is required when stdin is not a TTY", err=True)+ sys.exit(2)+ options = prompt_interactive_options(+ prompt=None,+ model=model,+ current_mode="collector",+ )+ if "command" in options:+ return+ prompt = options["prompt"]+ model = options.get("model") or model++ result = run_collector(prompt=prompt, model=model, output_dir=output_dir)+ if result is None or (isinstance(result, dict) and result.get("error")):+ sys.exit(1)++def run_manual_capture(prompt=None, url=None, reverse_engineer=True, model=None, output_dir=None):"""Shared logic for manual capture."""output_dir = output_dir or config_manager.get("output_dir")@@ -1762,12 +1825,17 @@ def run_collector(prompt=None, model=None, output_dir=None):usage=result.get("usage", {}),paths={"output_path": result.get("output_path")},)+ return resultexcept Exception as e:console.print(f" [red]collector error: {e}[/red]")console.print(f" [dim]{ERROR_CTA}[/dim]")import tracebacktraceback.print_exc()+ return {+ "run_id": run_id,+ "error": str(e) or type(e).__name__,+ }def run_auto_capture(@@ -1979,7 +2047,6 @@ def run_auto_capture(}-@main.command(epilog="""\bExamples:@@ -1997,8 +2064,16 @@ JSON output schema (--json):"prompt": "..." | null,"fresh": false,"script_path": "/abs/path/api_client.py" | null,- "usage": { "input_tokens": ..., "output_tokens": ..., "total_cost": ... },- "error": "<message>" | null+ "usage": {+ "input_tokens": ...,+ "output_tokens": ...,+ "cache_read_tokens": ...,+ "cache_write_tokens": ...,+ "total_cost_usd": ...,+ "raw": { ... }+ },+ "error": "<message>" | null,+ "error_kind": "misuse" | "config_invalid" | "permission_denied" | "network" | "engine_failure" | "interrupted" | "unknown" | null}\b@@ -2445,20 +2520,29 @@ def show_run(run_id, as_json):from rich.table import Tablefrom rich.text import Text+ def _show_error_payload(message: str, rid: str | None = None) -> dict:+ return {+ "schema_version": AGENT_JSON_SCHEMA_VERSION,+ "status": "error",+ "run_id": rid,+ "error": message,+ "error_kind": _classify_error(message, default="engine_failure"),+ }+if run_id:run = session_manager.get_run(run_id)elif session_manager.history:run = session_manager.history[0]else:if as_json:- click.echo(json.dumps({"error": "no runs found"}))+ click.echo(json.dumps(_show_error_payload("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}))+ click.echo(json.dumps(_show_error_payload("run not found", run_id)))sys.exit(1)console.print(f"Run not found: {run_id}")return@@ -2502,6 +2586,10 @@ def show_run(run_id, as_json):details["har_entries"] = har_entriesif as_json:+ details["schema_version"] = AGENT_JSON_SCHEMA_VERSION+ details["status"] = "ok"+ details["error"] = None+ details["error_kind"] = Noneclick.echo(json.dumps(details, indent=2))return@@ -2549,6 +2637,155 @@ def show_run(run_id, as_json):console.print(table)+def _run_script_machine_payload(+ *,+ identifier: str,+ script_args: tuple[str, ...],+ file_name: str | None,+ list_scripts: bool,+ auto_install: bool,+ emit_event,+) -> dict:+ """Run or list generated scripts without prompts and with JSON-safe stdout."""+ import re as _re+ import subprocess++ run_id: str | None = None+ script: Path | None = None+ scripts: list[Path] = []++ try:+ run = resolve_run(identifier, session_manager, interactive=False)+ run_id = run["run_id"]+ output_dir = config_manager.get("output_dir")+ scripts = discover_scripts(run_id, output_dir, run_metadata=run)+ emit_event("run_resolved", run_id=run_id, script_count=len(scripts))++ if not scripts:+ return _build_run_payload(+ identifier=identifier,+ run_id=run_id,+ scripts=scripts,+ error=f"No Python scripts found for run {run_id}",+ error_kind_hint="engine_failure",+ )++ if list_scripts:+ return _build_run_payload(+ identifier=identifier,+ run_id=run_id,+ scripts=scripts,+ returncode=0,+ )++ if file_name:+ matching = [s for s in scripts if s.name == file_name]+ if not matching:+ available = ", ".join(s.name for s in scripts)+ return _build_run_payload(+ identifier=identifier,+ run_id=run_id,+ scripts=scripts,+ error=f"'{file_name}' not found. Available: {available}",+ error_kind_hint="misuse",+ )+ script = matching[0]+ elif len(scripts) == 1:+ script = scripts[0]+ else:+ available = ", ".join(s.name for s in scripts)+ return _build_run_payload(+ identifier=identifier,+ run_id=run_id,+ scripts=scripts,+ error=(f"multiple scripts found for run {run_id}; pass --file <name> to choose. Available: {available}"),+ error_kind_hint="misuse",+ )++ emit_event("script_selected", run_id=run_id, script_path=str(script))++ from .utils import get_base_output_dir as _get_base++ venv_dir = _get_base(output_dir) / ".venv"+ venv_bin = "Scripts" if sys.platform == "win32" else "bin"+ venv_python = venv_dir / venv_bin / ("python.exe" if sys.platform == "win32" else "python")+ venv_pip = venv_dir / venv_bin / ("pip.exe" if sys.platform == "win32" else "pip")++ subprocess_kwargs = {"capture_output": True, "text": True}+ if not venv_dir.exists():+ emit_event("venv_setup_started", run_id=run_id, path=str(venv_dir))+ subprocess.run([sys.executable, "-m", "venv", str(venv_dir)], check=True, **subprocess_kwargs)+ subprocess.run([str(venv_pip), "install", "-q", "requests"], check=True, **subprocess_kwargs)+ emit_event("venv_setup_completed", run_id=run_id, path=str(venv_dir))++ requirements = script.parent / "requirements.txt"+ if requirements.exists():+ emit_event("requirements_install_started", run_id=run_id, path=str(requirements))+ subprocess.run([str(venv_pip), "install", "-q", "-r", str(requirements)], check=True, **subprocess_kwargs)+ emit_event("requirements_install_completed", run_id=run_id, path=str(requirements))++ cmd = [str(venv_python), str(script), *script_args]+ emit_event("process_started", run_id=run_id, script_path=str(script))+ result = subprocess.run(cmd, **subprocess_kwargs)++ stderr = result.stderr or ""+ if result.returncode != 0 and "ModuleNotFoundError: No module named" in stderr:+ match = _re.search(r"No module named ['\"]([^'\"]+)['\"]", stderr)+ if match:+ missing = match.group(1).split(".")[0]+ emit_event("dependency_missing", run_id=run_id, package=missing)+ if auto_install:+ emit_event("dependency_install_started", run_id=run_id, package=missing)+ subprocess.run([str(venv_pip), "install", "-q", missing], check=True, **subprocess_kwargs)+ emit_event("dependency_install_completed", run_id=run_id, package=missing)+ emit_event("process_retried", run_id=run_id, script_path=str(script))+ result = subprocess.run(cmd, **subprocess_kwargs)+ else:+ return _build_run_payload(+ identifier=identifier,+ run_id=run_id,+ script_path=str(script),+ script_args=script_args,+ returncode=result.returncode,+ stdout=result.stdout or "",+ stderr=stderr,+ scripts=scripts,+ error=f"missing dependency: {missing}",+ error_kind_hint="engine_failure",+ )++ return _build_run_payload(+ identifier=identifier,+ run_id=run_id,+ script_path=str(script),+ script_args=script_args,+ returncode=result.returncode,+ stdout=result.stdout or "",+ stderr=result.stderr or "",+ scripts=scripts,+ )+ except click.ClickException as e:+ return _build_run_payload(+ identifier=identifier,+ run_id=run_id,+ script_path=str(script) if script else None,+ script_args=script_args,+ scripts=scripts,+ error=e.message,+ error_kind_hint="misuse",+ )+ except Exception as e:+ return _build_run_payload(+ identifier=identifier,+ run_id=run_id,+ script_path=str(script) if script else None,+ script_args=script_args,+ scripts=scripts,+ error=e,+ error_kind_hint="engine_failure",+ )++@main.command("run",epilog="""\b@@ -2557,6 +2794,8 @@ Examples:reverse-api-engineer run ashby --lsreverse-api-engineer run ashby --file api_client.py -- --org acme --limit 10reverse-api-engineer run a450e520ca30 --file api_client.py --no-interactive --auto-install+ reverse-api-engineer run a450e520ca30 --file api_client.py --json | jq+ reverse-api-engineer run a450e520ca30 --file api_client.py --json-stream\bExit codes:@@ -2579,8 +2818,20 @@ Exit codes:is_flag=True,help="Auto-install missing dependencies on retry without prompting (implies --no-interactive for the picker).",)+ "--json",+ "as_json",+ is_flag=True,+ help="Emit one JSON result on stdout with captured script stdout/stderr. Implies --no-interactive.",+)+ "--json-stream",+ "json_stream",+ is_flag=True,+ help='Emit NDJSON progress events on stdout, then a final {"event":"result",...} line. Implies --no-interactive.',+)@click.pass_context-def run_script(ctx, identifier, script_args, file_name, list_scripts, no_interactive, auto_install):+def run_script(ctx, identifier, script_args, file_name, list_scripts, no_interactive, auto_install, as_json, json_stream):"""Run a generated script from a previous run.IDENTIFIER is a run ID or search term to match against prompts.@@ -2601,8 +2852,32 @@ def run_script(ctx, identifier, script_args, file_name, list_scripts, no_interacfrom rich.table import Table+ machine_output = as_json or json_stream+ no_interactive = no_interactive or machine_output++ if machine_output:+ with _quiet_consoles_for_json() as real_stdout:++ def emit_event(event: str, **fields) -> None:+ if json_stream:+ _write_json_event(real_stdout, {"event": event, **fields})++ payload = _run_script_machine_payload(+ identifier=identifier,+ script_args=script_args,+ file_name=file_name,+ list_scripts=list_scripts,+ auto_install=auto_install,+ emit_event=emit_event,+ )+ _write_json_stdout(real_stdout, payload, json_stream=json_stream)++ if payload["returncode"] not in (None, 0):+ raise SystemExit(payload["returncode"])+ raise SystemExit(0 if payload["status"] == "ok" else 1)+# Resolve which run- run = resolve_run(identifier, session_manager)+ run = resolve_run(identifier, session_manager, interactive=not no_interactive)run_id = run["run_id"]output_dir = config_manager.get("output_dir")diff --git a/src/reverse_api/utils.py b/src/reverse_api/utils.pyindex 6663b7e..3cb0dc9 100644--- a/src/reverse_api/utils.py+++ b/src/reverse_api/utils.py@@ -534,7 +534,7 @@ def get_visible_save_path(domain: str, base_dir: Path | str, suffix: int = 0) ->return path-def resolve_run(identifier: str, session_manager) -> dict:+def resolve_run(identifier: str, session_manager, *, interactive: bool = True) -> dict:"""Resolve a run by exact ID or fuzzy prompt/folder name match.Args:@@ -545,7 +545,8 @@ def resolve_run(identifier: str, session_manager) -> dict:The matching run dictRaises:- click.ClickException: If no match or ambiguous match without TTY+ click.ClickException: If no match or if multiple matches are found in+ non-interactive mode."""import clickimport questionary@@ -576,6 +577,12 @@ def resolve_run(identifier: str, session_manager) -> dict:if len(matches) == 1:return matches[0]+ if not interactive:+ available = ", ".join(m.get("run_id", "") for m in matches)+ raise click.ClickException(+ f"Multiple runs match '{identifier}'; pass an exact run_id. Available: {available}"+ )+# Multiple matches — show pickerchoices = []for m in matches:diff --git a/tests/test_cli_agent_json.py b/tests/test_cli_agent_json.pyindex 4bd7569..88799cb 100644--- a/tests/test_cli_agent_json.py+++ b/tests/test_cli_agent_json.py@@ -202,6 +202,9 @@ class TestShowJsonNotFound:result = runner.invoke(show_run, ["doesnotexist", "--json"])assert result.exit_code == 1payload = json.loads(result.stdout.strip())+ assert payload["schema_version"] == AGENT_JSON_SCHEMA_VERSION+ assert payload["status"] == "error"+ assert payload["error_kind"] == "engine_failure"assert "error" in payloadassert payload["run_id"] == "doesnotexist"@@ -329,6 +332,100 @@ class TestRunCommandNonInteractive:# Exit propagates the original failureassert result.exit_code != 0+ def test_fuzzy_multiple_matches_with_no_interactive_errors_without_picker(self, tmp_path):+ """--no-interactive must fail fast even before script selection."""+ sm = SessionManager(tmp_path / "history.json")+ sm.add_run("abc123def456", "capture ashby api", mode="manual")+ sm.add_run("def789ghi012", "capture hubspot api", mode="agent")++ runner = CliRunner()+ with (+ patch("reverse_api.cli.session_manager", sm),+ patch("questionary.select") as mock_select,+ ):+ result = runner.invoke(main, ["run", "api", "--no-interactive"])+ assert result.exit_code != 0+ assert "Multiple runs match" in result.output+ mock_select.assert_not_called()+++class TestRunCommandJson:+ """`run --json` / `--json-stream` should be safe for wrapper agents."""++ def _precreate_venv(self, tmp_path):+ venv = tmp_path / ".venv"+ (venv / "bin").mkdir(parents=True)+ (venv / "bin" / "python").write_text("#!/bin/sh")+ (venv / "bin" / "pip").write_text("#!/bin/sh")++ def test_run_json_captures_script_output(self, multi_script_env):+ tmp_path, _ = multi_script_env+ self._precreate_venv(tmp_path)++ runner = CliRunner()+ completed = MagicMock(returncode=0, stdout="hello\n", stderr="warn\n")+ with patch("subprocess.run", return_value=completed):+ result = runner.invoke(+ main,+ ["run", "abc123def456", "--file", "api_client.py", "--json"],+ )++ assert result.exit_code == 0, result.output+ payload = json.loads(result.stdout.strip())+ assert payload["schema_version"] == AGENT_JSON_SCHEMA_VERSION+ assert payload["status"] == "ok"+ assert payload["run_id"] == "abc123def456"+ assert payload["script_path"].endswith("api_client.py")+ assert payload["stdout"] == "hello\n"+ assert payload["stderr"] == "warn\n"++ def test_run_json_multiple_scripts_requires_file_without_picker(self, multi_script_env):+ runner = CliRunner()+ with patch("questionary.select") as mock_select:+ result = runner.invoke(main, ["run", "abc123def456", "--json"])++ assert result.exit_code == 1+ payload = json.loads(result.stdout.strip())+ assert payload["status"] == "error"+ assert payload["error_kind"] == "misuse"+ assert "multiple scripts" in payload["error"]+ assert {s["name"] for s in payload["scripts"]} == {"api_client.py", "example_usage.py"}+ mock_select.assert_not_called()++ def test_run_json_stream_emits_events_and_result(self, multi_script_env):+ tmp_path, _ = multi_script_env+ self._precreate_venv(tmp_path)++ runner = CliRunner()+ completed = MagicMock(returncode=0, stdout="ok\n", stderr="")+ with patch("subprocess.run", return_value=completed):+ result = runner.invoke(+ main,+ ["run", "abc123def456", "--file", "api_client.py", "--json-stream"],+ )++ assert result.exit_code == 0, result.output+ events = [json.loads(line) for line in result.stdout.strip().splitlines()]+ assert [event["event"] for event in events[:3]] == [+ "run_resolved",+ "script_selected",+ "process_started",+ ]+ assert events[-1]["event"] == "result"+ assert events[-1]["status"] == "ok"+ assert events[-1]["stdout"] == "ok\n"++ def test_run_ls_json_lists_scripts_without_executing(self, multi_script_env):+ runner = CliRunner()+ with patch("subprocess.run") as mock_sub:+ result = runner.invoke(main, ["run", "abc123def456", "--ls", "--json"])++ assert result.exit_code == 0, result.output+ payload = json.loads(result.stdout.strip())+ assert payload["status"] == "ok"+ assert {s["name"] for s in payload["scripts"]} == {"api_client.py", "example_usage.py"}+ mock_sub.assert_not_called()+# ---------------------------------------------------------------------------# Agent --json: interruption + stdout-puritydiff --git a/tests/test_cli_followups.py b/tests/test_cli_followups.pyindex eaf4952..2fd6ee5 100644--- a/tests/test_cli_followups.py+++ b/tests/test_cli_followups.py@@ -719,31 +719,27 @@ class TestFollowUpPromptSuppressed:class TestHeadlessFlag:- """`--headless` wires through to auto-engineer constructors (agent only —- manual mode is intentionally human-only and rejects --headless)."""+ """`--headless` wires through to auto-engineer constructors.- def test_manual_rejects_headless_flag(self):- """`manual --headless` must fail: manual mode requires a human and a- visible browser; agents should use `agent --headless` instead."""- from reverse_api.cli import manual as manual_cmd+ Manual mode is intentionally REPL-only, so there is no direct `manual`+ subcommand to parse scripted/headless flags.+ """++ def test_manual_is_not_a_direct_subcommand(self):+ from reverse_api.cli import mainrunner = CliRunner()- result = runner.invoke(manual_cmd, ["-p", "x", "-u", "https://example.com", "--headless"])+ result = runner.invoke(main, ["manual"])assert result.exit_code != 0- assert "no such option" in result.output.lower() or "--headless" in result.output+ assert "no such command 'manual'" in result.output.lower()- def test_manual_help_mentions_human_only(self):- """`manual --help` must make it explicit that the mode requires a- human and is not scriptable (so agents inspecting --help self-route- to `agent` instead)."""- from reverse_api.cli import manual as manual_cmd+ def test_manual_is_absent_from_root_help(self):+ from reverse_api.cli import mainrunner = CliRunner()- result = runner.invoke(manual_cmd, ["--help"])+ result = runner.invoke(main, ["--help"])assert result.exit_code == 0- out = result.output.lower()- assert "human" in out- assert "agent" in out # tells the agent where to go instead+ assert " manual " not in result.outputdef test_agent_command_threads_headless(self):from reverse_api.cli import agent as agent_cmd@@ -764,6 +760,59 @@ class TestHeadlessFlag:assert mock_run.call_args.kwargs["headless"] is False+class TestCollectorCommand:+ """Direct `collector` command wiring."""++ def test_collector_command_threads_prompt_model_and_output_dir(self):+ from reverse_api.cli import collector as collector_cmd++ runner = CliRunner()+ with patch("reverse_api.cli.run_collector", return_value={"output_path": "/tmp/out"}) as mock_run:+ result = runner.invoke(+ collector_cmd,+ [+ "--prompt",+ "collect one item",+ "--model",+ "claude-haiku-4-5",+ "--output-dir",+ "/tmp/rae-test",+ ],+ )+ assert result.exit_code == 0, result.output+ assert mock_run.call_args.kwargs == {+ "prompt": "collect one item",+ "model": "claude-haiku-4-5",+ "output_dir": "/tmp/rae-test",+ }++ def test_collector_requires_prompt_when_not_tty(self):+ from reverse_api.cli import collector as collector_cmd++ runner = CliRunner()+ with patch("reverse_api.cli.run_collector") as mock_run:+ result = runner.invoke(collector_cmd, [])+ assert result.exit_code == 2+ assert "--prompt is required" in result.output+ mock_run.assert_not_called()++ def test_collector_exits_nonzero_on_error_result(self):+ from reverse_api.cli import collector as collector_cmd++ runner = CliRunner()+ with patch("reverse_api.cli.run_collector", return_value={"error": "No items collected"}):+ result = runner.invoke(collector_cmd, ["--prompt", "collect nothing"])+ assert result.exit_code == 1++ def test_collector_exits_nonzero_on_empty_result(self):+ from reverse_api.cli import collector as collector_cmd++ runner = CliRunner()+ with patch("reverse_api.cli.run_collector", return_value=None):+ result = runner.invoke(collector_cmd, ["--prompt", "collect nothing"])+ assert result.exit_code == 1++class TestHeadlessMcpConfig:"""ClaudeAutoEngineer._get_mcp_config arg construction for headed vs headless."""diff --git a/website/content/docs/cli/commands.mdx b/website/content/docs/cli/commands.mdxindex 6b83892..930575d 100644--- a/website/content/docs/cli/commands.mdx+++ b/website/content/docs/cli/commands.mdx@@ -10,7 +10,7 @@ While in the interactive prompt, the following slash commands are available:| `/settings` | Configure model, agent provider, SDK, output directory. || `/history` | View past runs with token usage and cost. || `/messages <run_id>` | View the full message log for a previous run. |-| `/help` | List all commands. |+| `/help` | List all commands. Alias: `/commands`. || `/exit` | Quit the CLI. |## Mode cycling@@ -24,17 +24,23 @@ agent → manual → engineer → collector → agent ...The current mode is shown in the prompt. Each mode has its own behavior. See[Usage modes](/docs/modes/manual).-## Listing and inspecting runs+## Direct subcommandsOutside the interactive CLI, you can use direct subcommands:-```bash-# list all runs-reverse-api-engineer list--# inspect a single run-reverse-api-engineer show <run_id>-```--Both accept `--json` for machine-parseable output. See+| Command | What it does |+|---------------|------------------------------------------------------------|+| `agent` | Run an autonomous browser capture and generation pipeline. |+| `collector` | Run AI-powered data collection and export JSON/CSV files. |+| `engineer` | Re-run generation against an existing capture. |+| `list` | List generated scripts and runs; supports `--json`. |+| `show` | Inspect one run; supports `--json`. |+| `run` | Execute a generated Python script; supports `--json`. |++Scripted flags are command-specific: `agent`, `engineer`, and `run` support+`--json` and `--json-stream`; `list` and `show` support `--json`; and `run`+also supports `--no-interactive` for script selection and dependency prompts. See[Scripted usage](/docs/cli/scripted-usage).++Manual mode is available only inside the interactive REPL because it opens a+visible browser for human-driven capture.diff --git a/website/content/docs/cli/scripted-usage.mdx b/website/content/docs/cli/scripted-usage.mdxindex 87c857c..2a8f113 100644--- a/website/content/docs/cli/scripted-usage.mdx+++ b/website/content/docs/cli/scripted-usage.mdx@@ -5,8 +5,8 @@ description: Drive the CLI from another agent or a wrapper script with --no-inteThe CLI can be driven by another agent, a CI job, or a wrapper script. Use`agent --json` or `engineer --json` for a single machine-readable result,-`list --json` and `show --json` for history inspection, and `run---no-interactive` to avoid script-picker and dependency prompts.+`list --json` and `show --json` for history inspection, and `run --json` to+execute generated scripts without contaminating stdout.When `--json` is set:@@ -14,11 +14,14 @@ When `--json` is set:- **stderr** receives Rich logs and progress updates.- The process exits with a **stable exit code**.-When `--json-stream` is set (on `agent` and `engineer`):+When `--json-stream` is set (on `agent`, `engineer`, and `run`):- **stdout** receives **NDJSON**: one JSON object per line while the run progresses, then a final `{"event":"result",...}` line with the same fields as `--json`.- **stderr** receives Rich logs (same as `--json`).-- Implies **non-interactive** mode; `AskUserQuestion` is auto-answered with a fixed message instead of prompting on stdin.+- Implies **non-interactive** mode. Engineer runs answer `AskUserQuestion`+ with a fixed non-interactive message; agent runs do not prompt on stdin and+ skip human answers; script runs never open the run/script picker or install+ confirm prompt.## Examples@@ -40,7 +43,20 @@ reverse-api-engineer agent \--json-stream```-Common event types: `run_started` (includes `run_id`, `sdk`; agent runs also include `mode`, `url`, `command`), `tool_start`, `tool_end`, `thinking`, `ask_user_skipped`, `result`.+Common event types for `agent` and `engineer`: `run_started` (includes `run_id`, `sdk`; agent runs also include `mode`, `url`, `command`), `tool_start`, `tool_end`, `thinking`, `ask_user_skipped`, `result`.++### Validate an agent run without launching a browser++```bash+reverse-api-engineer agent \+ --prompt "capture the public jobs api" \+ --url https://example.com/jobs \+ --dry-run | jq+```++`--dry-run` implies `--json`, validates prompt/URL/config/environment, returns+`would_run` plus `checks`, and exits `0` when all checks pass or `1` when any+check has `status: "error"`.### List and inspect runs@@ -52,14 +68,19 @@ reverse-api-engineer list --jsonreverse-api-engineer show <run_id> --json```-### Run a generated script non-interactively+### Run a generated script from another agent```bashreverse-api-engineer run <run_id> --file api_client.py \- --no-interactive --auto-install -- --org acme+ --json --auto-install -- --org acme```-- `--no-interactive`: never open the script-picker or install confirm.+- `--json`: captures the generated script's stdout/stderr into the result+ payload and implies `--no-interactive`.+- `--json-stream`: emits NDJSON events such as `run_resolved`,+ `script_selected`, `process_started`, and final `result`.+- `--no-interactive`: never open the run picker, script picker, or install+ confirm.- `--auto-install`: install missing deps on retry without asking.- Everything after `--` is forwarded to the underlying script.@@ -79,6 +100,13 @@ reverse-api-engineer run <run_id> --file api_client.py \| `error` | `string \| null` | Human-readable error message when `status == "error"`. || `error_kind` | `string \| null` | Machine-readable error category such as `misuse`, `network`, or `engine_failure`. |+`engineer --json` uses the same top-level contract, minus agent-only fields+(`url`, `mode`, `har_path`) and plus `fresh`. `run --json` uses the same+`schema_version`, `status`, `error`, and `error_kind` fields, plus+`identifier`, `run_id`, `script_path`, `script_args`, `returncode`, `stdout`,+`stderr`, and `scripts`. `show --json` includes `schema_version`, `status`,+`error`, and `error_kind` in addition to the run details.+## Exit codes| Code | Meaning |@@ -87,6 +115,8 @@ reverse-api-engineer run <run_id> --file api_client.py \| `1` | Runtime error (capture or engineering failed; details in `error`). || `2` | Misuse: required arg missing under `--no-interactive` / `--json`. |-For `run`, the exit code is the underlying script's return code on success,-or `1` if no script was found, or non-zero if `--no-interactive` would-otherwise have to prompt.+For `run`, the exit code is the underlying script's return code when a script+executes, or `1` if no script was found, no exact script was selected, or+`--no-interactive` would otherwise have to prompt. Under `--json`, the+generated script's stdout and stderr are captured into JSON fields instead of+being written directly to stdout.diff --git a/website/content/docs/configuration/agent.mdx b/website/content/docs/configuration/agent.mdxindex 571483f..368cadb 100644--- a/website/content/docs/configuration/agent.mdx+++ b/website/content/docs/configuration/agent.mdx@@ -10,8 +10,8 @@ Agent mode runs an AI loop. **`auto`** and **`chrome-mcp`** attach browser autom### `auto` (default)Playwright MCP browser automation with real-time reverse engineering. The-configured SDK uses Playwright via MCP to control a headless (or headed)-Chromium, capturing the HAR as it goes.+configured SDK uses Playwright via MCP to control Chromium, capturing the HAR+as it goes. Add `--headless` when running without a display.Works with the Claude SDK (default) or the OpenCode SDK. Pick whicheveryou've already configured. Copilot and Cursor SDK backends are also supporteddiff --git a/website/content/docs/configuration/models.mdx b/website/content/docs/configuration/models.mdxindex 2c4514f..3d57af7 100644--- a/website/content/docs/configuration/models.mdx+++ b/website/content/docs/configuration/models.mdx@@ -19,10 +19,10 @@ In the CLI:/settings then "Claude Code Model"```-Or pass at launch:+Or pass a model to a direct command:```bash-reverse-api-engineer manual --model claude-sonnet-4-6+reverse-api-engineer agent --prompt "capture the jobs api" --model claude-sonnet-4-6```Or edit `~/.reverse-api/config.json` directly:@@ -40,6 +40,8 @@ The full default config:```json{"agent_provider": "auto",+ "agent_browser_notes": "",+ "agent_browser_npx_package": "agent-browser@0","claude_code_model": "claude-sonnet-4-6","collector_model": "claude-sonnet-4-6","cursor_model": "composer-2.5",diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdxindex 5e07dde..dbcbff8 100644--- a/website/content/docs/index.mdx+++ b/website/content/docs/index.mdx@@ -48,11 +48,11 @@ or too time-consuming to map by hand:### Drive captures from another agent-Scripted commands are available for agent workflows. `agent` and `engineer`-support `--json` plus non-interactive execution, `list` and `show` support-JSON output, and `run` supports `--no-interactive` for script selection and-dependency prompts. Easy to wrap in a CI job, a [Claude Agent SDK][agent-sdk]-loop, or a cron task.+Scripted commands are available for agent workflows. `agent`, `engineer`, and+`run` support JSON output plus non-interactive execution, `agent`, `engineer`,+and `run` can stream NDJSON progress with `--json-stream`, and `list` plus+`show` support JSON history inspection. Easy to wrap in a CI job, a+[Claude Agent SDK][agent-sdk] loop, or a cron task.[agent-sdk]: https://code.claude.com/docs/en/agent-sdk/@@ -66,20 +66,23 @@ bodies, response bodies, timing.### Autonomous agent loop-Plug an MCP-driven agent into the loop and it browses on your behalf. Two-providers shipped:+Plug an agent into the loop and it browses on your behalf. Three providers+ship today:-- **Playwright MCP** *(default)*: headless capture, fully self-contained.-- **Chrome DevTools MCP**: drives your **real Chrome** with existing- sessions, cookies, and auth.+- **Playwright MCP** *(default)*: self-contained browser automation; add+ `--headless` for CI or machines without a display.+- **Chrome DevTools MCP**: drives your **real Chrome** with existing sessions,+ cookies, and auth.+- **agent-browser**: delegates browsing to the Vercel `agent-browser` CLI+ after resolving a PATH/global/npm/npx shell invocation.The agent reverse-engineers the API in real time while it browses, so by thetime the run ends, the client is already generated.-### AI-powered codegen with Claude+### AI-powered codegen-The HAR is fed to your configured model (Claude by default) along with a tuned-system prompt. Output:+The HAR is fed to your configured SDK model (Claude by default) along with a+tuned system prompt. Output:- Typed Python (or TS / JS) clients with docstrings.- Authentication handling: cookies, bearers, CSRF tokens.diff --git a/website/content/docs/modes/agent.mdx b/website/content/docs/modes/agent.mdxindex bb2043c..193ae64 100644--- a/website/content/docs/modes/agent.mdx+++ b/website/content/docs/modes/agent.mdx@@ -23,7 +23,7 @@ English; providers such as Playwright MCP or Chrome DevTools MCP route browser a```bashreverse-api-engineer-# switch to agent mode with Shift+Tab+# the REPL starts in agent mode> click on the first job listing```@@ -40,6 +40,28 @@ The `--json` flag makes the command emit a single JSON document on stdout(see [Scripted usage](/docs/cli/scripted-usage) for the schema and exitcodes).+Use `--json-stream` when a supervising agent wants NDJSON progress events+during the browser and generation loop:++```bash+reverse-api-engineer agent \+ --prompt "capture the public jobs api" \+ --url https://example.com/jobs \+ --json-stream+```++For wrapper or CI validation without launching a browser, use:++```bash+reverse-api-engineer agent \+ --prompt "capture the public jobs api" \+ --url https://example.com/jobs \+ --dry-run+```++`--dry-run` implies JSON output and checks prompt, URL, SDK config, browser+tooling, and output directory writability.+## Agent providersPick the provider in `/settings` then "agent provider".diff --git a/website/content/docs/modes/collector.mdx b/website/content/docs/modes/collector.mdxnew file mode 100644index 0000000..8a54878--- /dev/null+++ b/website/content/docs/modes/collector.mdx@@ -0,0 +1,41 @@+---+title: Collector mode+description: Use an AI agent to collect structured web data as JSON and CSV.+---++Collector mode is an interactive REPL mode for data collection tasks. Instead+of generating an API client from a HAR, it runs a Claude-powered collector that+uses web search and fetch tools, writes collected items, and exports structured+artifacts.++## When to use it++- You want a dataset, not a reusable API client.+- The task is research or aggregation across multiple web pages.+- JSON/CSV output is more useful than generated request code.++## How to run it++Direct:++```bash+reverse-api-engineer collector \+ --prompt "collect companies hiring browser automation engineers"+```++Interactive:++```bash+reverse-api-engineer+# press Shift+Tab until the prompt shows collector+> collect companies hiring browser automation engineers+```++Collector mode uses the `collector_model` config key and writes output under:++```text+./collected/{folder_name}/+```++Typical files include `items.jsonl`, `data.json`, `data.csv`, and+`README.md`, depending on what the collector finds.diff --git a/website/content/docs/modes/engineer.mdx b/website/content/docs/modes/engineer.mdxindex 3789366..e676e0d 100644--- a/website/content/docs/modes/engineer.mdx+++ b/website/content/docs/modes/engineer.mdx@@ -30,6 +30,17 @@ Direct:reverse-api-engineer engineer <run_id>```+From another agent or CI wrapper:++```bash+reverse-api-engineer engineer <run_id> \+ --prompt "add pagination support" \+ --json-stream+```++Use `--json` when you only need the final result. Both JSON modes suppress+follow-up prompts and keep machine-readable output on stdout.+Find the `run_id` of a previous run with:```bashdiff --git a/website/content/docs/modes/manual.mdx b/website/content/docs/modes/manual.mdxindex ee552da..84a037a 100644--- a/website/content/docs/modes/manual.mdx+++ b/website/content/docs/modes/manual.mdx@@ -1,6 +1,6 @@---title: Manual mode-description: You drive the browser, the AI writes the client. The default workflow.+description: You drive the browser, the AI writes the client.---Manual mode runs the full pipeline with you in the driver's seat.@@ -15,10 +15,14 @@ Manual mode runs the full pipeline with you in the driver's seat.<Steps><Step>- Start the CLI:+ Start the interactive REPL:```bashreverse-api-engineer```++ Press **`Shift+Tab`** once from the default agent prompt to switch into+ manual mode. Manual mode is REPL-only because it requires a human in front+ of a visible browser.</Step><Step>Enter a task description (e.g. *"Fetch Apple job listings"*).diff --git a/website/content/docs/modes/meta.json b/website/content/docs/modes/meta.jsonindex 86bf44a..e135d16 100644--- a/website/content/docs/modes/meta.json+++ b/website/content/docs/modes/meta.json@@ -1,4 +1,4 @@{"title": "Usage modes",- "pages": ["manual", "engineer", "agent"]+ "pages": ["manual", "engineer", "agent", "collector"]}diff --git a/website/content/docs/quick-start.mdx b/website/content/docs/quick-start.mdxindex 9e60882..1d84958 100644--- a/website/content/docs/quick-start.mdx+++ b/website/content/docs/quick-start.mdx@@ -77,7 +77,7 @@ description: From a fresh install to a working API client in under five minutes.```bashreverse-api-engineer run <run_id> --file api_client.py \- --no-interactive --auto-install+ --json --auto-install```</Step></Steps>@@ -85,7 +85,7 @@ description: From a fresh install to a working API client in under five minutes.## Next steps<Cards>- <Card title="Modes in depth" href="/docs/modes/manual" description="When to use Manual vs Engineer vs Agent." />+ <Card title="Modes in depth" href="/docs/modes/manual" description="When to use Agent, Manual, Engineer, or Collector." /><Card title="Configure your model" href="/docs/configuration/models" description="Pick between Sonnet, Opus, Haiku." /><Card title="Scripted usage" href="/docs/cli/scripted-usage" description="Run from another agent with --json output." /></Cards>