Skip to content

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.py
index 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 definitions
MODES = ["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="""\b
Examples:
@@ -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 result
except Exception as e:
console.print(f" [red]collector error: {e}[/red]")
console.print(f" [dim]{ERROR_CTA}[/dim]")
import traceback
traceback.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="""\b
Examples:
@@ -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 Table
from 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")
return
if 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_entries
if as_json:
+ details["schema_version"] = AGENT_JSON_SCHEMA_VERSION
+ details["status"] = "ok"
+ details["error"] = None
+ details["error_kind"] = None
click.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 --ls
reverse-api-engineer run ashby --file api_client.py -- --org acme --limit 10
reverse-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
\b
Exit 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_interac
from 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.py
index 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 dict
Raises:
- 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 click
import 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 picker
choices = []
for m in matches:
diff --git a/tests/test_cli_agent_json.py b/tests/test_cli_agent_json.py
index 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 == 1
payload = 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 payload
assert payload["run_id"] == "doesnotexist"
@@ -329,6 +332,100 @@ class TestRunCommandNonInteractive:
# Exit propagates the original failure
assert 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-purity
diff --git a/tests/test_cli_followups.py b/tests/test_cli_followups.py
index 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 main
runner = 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 main
runner = 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.output
def 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.mdx
index 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 subcommands
Outside 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.mdx
index 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-inte
The 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 --json
reverse-api-engineer show <run_id> --json
```
-### Run a generated script non-interactively
+### Run a generated script from another agent
```bash
reverse-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.mdx
index 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 whichever
you've already configured. Copilot and Cursor SDK backends are also supported
diff --git a/website/content/docs/configuration/models.mdx b/website/content/docs/configuration/models.mdx
index 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.mdx
index 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 the
time 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.mdx
index 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
```bash
reverse-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 exit
codes).
+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 providers
Pick the provider in `/settings` then "agent provider".
diff --git a/website/content/docs/modes/collector.mdx b/website/content/docs/modes/collector.mdx
new file mode 100644
index 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.mdx
index 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:
```bash
diff --git a/website/content/docs/modes/manual.mdx b/website/content/docs/modes/manual.mdx
index 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:
```bash
reverse-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.json
index 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.mdx
index 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.
```bash
reverse-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>