Skip to content

The agent that turns websites into APIs!

feat(cli): expand agent-friendly tests, --help epilogs and README

Kalil Bouziguesab5b57963716
diff --git a/README.md b/README.md
index c65e249..e5dc7af 100644
--- a/README.md
+++ b/README.md
@@ -358,7 +358,9 @@ Use these slash commands while in the CLI:
### 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.
+The CLI subcommands can be driven by another agent or a wrapper script. Pass `--no-interactive` (and/or `--json`) so they fail fast instead of opening questionary prompts, and pipe the structured output into `jq`.
+
+When `--json` is set: stdout contains exactly one JSON document (the final result), Rich logs and progress are diverted to stderr, and the process exits with a stable code.
```bash
# Run an autonomous agent capture and get a single JSON result on stdout
@@ -367,30 +369,41 @@ reverse-api-engineer agent \
--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
+# Run a generated script non-interactively
+# --no-interactive : never open the script-picker / install confirm
+# --auto-install : install missing deps on retry without asking
+reverse-api-engineer run <run_id> --file api_client.py \
+ --no-interactive --auto-install -- --org acme
```
-Exit codes: `0` success, `1` runtime error, `2` misuse (missing required args).
+#### `agent --json` output schema
+
+| Field | Type | Notes |
+|------------------|---------------------|------------------------------------------------------------------------|
+| `schema_version` | `int` | Currently `1`. Bumped on breaking changes. |
+| `status` | `"ok"` \| `"error"` | Top-level result. |
+| `run_id` | `string` \| `null` | Stable id for follow-up `show` / `engineer` / `run` calls. |
+| `prompt` | `string` | The prompt that was passed in. |
+| `url` | `string` \| `null` | Optional starting URL. |
+| `mode` | `string` \| `null` | Provider used (`"auto"` for Playwright MCP, `"chrome-mcp"`). |
+| `har_path` | `string` \| `null` | Absolute path to the captured HAR (`recording.har`). |
+| `script_path` | `string` \| `null` | Absolute path to the generated client when reverse engineering ran. |
+| `usage` | `object` | Token + cost usage from the engineer SDK (`{input_tokens, output_tokens, total_cost}`).|
+| `error` | `string` \| `null` | Human-readable error message when `status == "error"`. |
+
+#### Exit codes
+
+| Code | Meaning |
+|------|---------------------------------------------------------------------------|
+| `0` | Success. |
+| `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.
## πŸ”Œ Claude Code Plugin
diff --git a/src/reverse_api/cli.py b/src/reverse_api/cli.py
index 831515a..0038ba3 100644
--- a/src/reverse_api/cli.py
+++ b/src/reverse_api/cli.py
@@ -1307,7 +1307,35 @@ def manual(prompt, url, reverse_engineer, model, output_dir):
run_manual_capture(prompt, url, reverse_engineer, model, output_dir)
+ epilog="""\b
+Examples:
+ reverse-api-engineer agent
+ reverse-api-engineer agent -p "capture the jobs api" -u https://example.com --no-interactive
+ reverse-api-engineer agent -p "capture the jobs api" --json | jq
+
+\b
+JSON output schema (--json):
+ {
+ "schema_version": 1,
+ "status": "ok" | "error",
+ "run_id": "<id>" | null,
+ "prompt": "...",
+ "url": "..." | null,
+ "mode": "auto" | "chrome-mcp" | 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
+ }
+
+\b
+Exit codes:
+ 0 success
+ 1 runtime error (capture or engineering failed)
+ 2 misuse (e.g. --prompt missing under --no-interactive / --json)
+"""
+)
@click.option("--prompt", "-p", default=None, help="Instruction for the autonomous agent.")
@click.option("--url", "-u", default=None, help="Optional starting URL.")
@click.option(
@@ -1995,7 +2023,16 @@ def _get_run_details(run: dict) -> dict:
}
+ "list",
+ epilog="""\b
+Examples:
+ reverse-api-engineer list
+ reverse-api-engineer list --mode auto --search jobs --json | jq
+
+JSON output (--json) is always a flat array (possibly empty []).
+""",
+)
@click.option("--json", "as_json", is_flag=True, help="Output as flat JSON array.")
@click.option("--full", is_flag=True, help="Show all columns (default: compact view).")
@click.option("--limit", "-n", type=int, default=None, help="Limit number of results.")
@@ -2076,7 +2113,19 @@ def list_runs(as_json, full, limit, mode, model, search):
console.print(table)
+ "show",
+ epilog="""\b
+Examples:
+ reverse-api-engineer show
+ reverse-api-engineer show <run_id> --json | jq
+
+\b
+Exit codes (--json):
+ 0 run found
+ 1 run not found / no history
+""",
+)
@click.argument("run_id", required=False)
@click.option("--json", "as_json", is_flag=True, help="Output as JSON object.")
def show_run(run_id, as_json):
@@ -2188,7 +2237,22 @@ def show_run(run_id, as_json):
console.print(table)
+ "run",
+ epilog="""\b
+Examples:
+ reverse-api-engineer run a450e520ca30
+ 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
+
+\b
+Exit codes:
+ <script's exit code> the underlying script's return code (0 on success)
+ 1 no script found for the run
+ non-zero missing --file when multiple scripts exist under --no-interactive
+""",
+)
@click.argument("identifier")
@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).")
diff --git a/tests/test_cli_agent_json.py b/tests/test_cli_agent_json.py
index f8dca12..72672d0 100644
--- a/tests/test_cli_agent_json.py
+++ b/tests/test_cli_agent_json.py
@@ -1,8 +1,9 @@
"""Tests for the agent-friendly CLI surface (--json, --no-interactive, payload shape)."""
import json
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
+import pytest
from click.testing import CliRunner
from reverse_api.cli import (
@@ -10,8 +11,10 @@ from reverse_api.cli import (
_build_agent_payload,
agent,
list_runs,
+ main,
show_run,
)
+from reverse_api.session import SessionManager
class TestBuildAgentPayload:
@@ -136,3 +139,169 @@ class TestShowJsonNotFound:
payload = json.loads(result.stdout.strip())
assert "error" in payload
assert payload["run_id"] == "doesnotexist"
+
+
+# ---------------------------------------------------------------------------
+# `run` command: --no-interactive and --auto-install behavior
+# ---------------------------------------------------------------------------
+
+
+def multi_script_env(tmp_path):
+ """Fake a run with multiple .py scripts on disk so the picker would normally fire."""
+ history_path = tmp_path / "history.json"
+ sm = SessionManager(history_path)
+ sm.add_run(
+ "abc123def456",
+ "capture the ashby jobs api",
+ mode="manual",
+ paths={"script_path": "/scripts/abc123def456/api_client.py"},
+ )
+ scripts_dir = tmp_path / "scripts" / "abc123def456"
+ scripts_dir.mkdir(parents=True)
+ (scripts_dir / "api_client.py").write_text("print('client')")
+ (scripts_dir / "example_usage.py").write_text("print('example')")
+
+ patches = [
+ patch("reverse_api.cli.session_manager", sm),
+ patch("reverse_api.cli.config_manager", MagicMock(get=MagicMock(return_value=None))),
+ patch("reverse_api.utils.get_base_output_dir", return_value=tmp_path),
+ ]
+ for p in patches:
+ p.start()
+ try:
+ yield tmp_path, sm
+ finally:
+ for p in patches:
+ p.stop()
+
+
+class TestRunCommandNonInteractive:
+ """`run` should never block on questionary when --no-interactive or --auto-install is set."""
+
+ def test_multiple_scripts_with_no_interactive_errors(self, multi_script_env):
+ runner = CliRunner()
+ with patch("questionary.select") as mock_select:
+ result = runner.invoke(main, ["run", "abc123def456", "--no-interactive"])
+ assert result.exit_code != 0
+ # Picker must NOT have been opened
+ mock_select.assert_not_called()
+ assert "multiple scripts" in result.output.lower() or "available" in result.output.lower()
+
+ def test_multiple_scripts_with_auto_install_errors_on_picker(self, multi_script_env):
+ """--auto-install also implies non-interactive for the picker."""
+ runner = CliRunner()
+ with patch("questionary.select") as mock_select:
+ result = runner.invoke(main, ["run", "abc123def456", "--auto-install"])
+ assert result.exit_code != 0
+ mock_select.assert_not_called()
+
+ def test_no_interactive_with_file_flag_runs(self, multi_script_env):
+ """--file disambiguates and the script runs without prompting."""
+ runner = CliRunner()
+ ok = MagicMock(returncode=0, stdout="", stderr="")
+ with patch("subprocess.run", return_value=ok) as mock_sub, patch("questionary.select") as mock_select:
+ result = runner.invoke(
+ main, ["run", "abc123def456", "--file", "api_client.py", "--no-interactive"]
+ )
+ assert result.exit_code == 0
+ mock_select.assert_not_called()
+ assert mock_sub.called
+
+ def test_auto_install_skips_questionary_confirm(self, multi_script_env):
+ """When the script raises ModuleNotFoundError, --auto-install skips the confirm prompt."""
+ runner = CliRunner()
+ # First subprocess.run returns missing-module error; subsequent ones (venv setup, pip install, retry)
+ # all succeed.
+ first = MagicMock(returncode=1, stdout="", stderr="ModuleNotFoundError: No module named 'foo'")
+ ok = MagicMock(returncode=0, stdout="", stderr="")
+
+ def fake_subprocess(cmd, *args, **kwargs):
+ # Detect the script execution call by looking for the .py path
+ cmd_str = " ".join(str(c) for c in cmd)
+ if cmd_str.endswith("api_client.py") or "api_client.py" in cmd_str:
+ # First and second invocation of the script path
+ fake_subprocess.script_calls += 1
+ if fake_subprocess.script_calls == 1:
+ return first
+ return ok
+
+ fake_subprocess.script_calls = 0
+
+ with patch("subprocess.run", side_effect=fake_subprocess), patch("questionary.confirm") as mock_confirm:
+ result = runner.invoke(
+ main, ["run", "abc123def456", "--file", "api_client.py", "--auto-install"]
+ )
+ # questionary.confirm must never have been called
+ mock_confirm.assert_not_called()
+ # Final exit code should be from the retry (success)
+ assert result.exit_code == 0
+
+ def test_no_interactive_skips_confirm_and_does_not_install(self, multi_script_env):
+ """--no-interactive (without --auto-install) must NOT install missing deps; it surfaces the failure."""
+ runner = CliRunner()
+ first = MagicMock(returncode=1, stdout="", stderr="ModuleNotFoundError: No module named 'foo'")
+ ok = MagicMock(returncode=0, stdout="", stderr="")
+
+ def fake_subprocess(cmd, *args, **kwargs):
+ cmd_str = " ".join(str(c) for c in cmd)
+ if "api_client.py" in cmd_str:
+ fake_subprocess.script_calls += 1
+ if fake_subprocess.script_calls == 1:
+ return first
+ # pip install must NOT happen β€” assert it
+ if "pip" in cmd_str and "install" in cmd_str and "foo" in cmd_str:
+ pytest.fail("pip should not have been called to install 'foo' under --no-interactive")
+ return ok
+
+ fake_subprocess.script_calls = 0
+
+ with patch("subprocess.run", side_effect=fake_subprocess), patch("questionary.confirm") as mock_confirm:
+ result = runner.invoke(
+ main, ["run", "abc123def456", "--file", "api_client.py", "--no-interactive"]
+ )
+ mock_confirm.assert_not_called()
+ # Exit propagates the original failure
+ assert result.exit_code != 0
+
+
+# ---------------------------------------------------------------------------
+# Agent --json: interruption + stdout-purity
+# ---------------------------------------------------------------------------
+
+
+class TestAgentJsonInterruption:
+ def test_keyboard_interrupt_emits_error_payload(self):
+ runner = CliRunner()
+ with patch("reverse_api.cli.run_agent_capture", side_effect=KeyboardInterrupt):
+ 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"] == "interrupted"
+
+
+class TestAgentJsonStdoutPurity:
+ """Stdout should contain exactly one JSON line; Rich noise must go to stderr."""
+
+ def test_rich_console_output_does_not_contaminate_stdout(self):
+ from reverse_api.cli import console as cli_console
+
+ # Click 8.2+ separates stdout/stderr by default
+ runner = CliRunner()
+
+ def fake_capture(**kwargs):
+ cli_console.print("noisy human-readable status")
+ return {"run_id": "abc", "mode": "auto", "script_path": None, "usage": {}}
+
+ with patch("reverse_api.cli.run_agent_capture", side_effect=fake_capture):
+ result = runner.invoke(agent, ["--json", "-p", "x"])
+
+ assert result.exit_code == 0
+ # stdout is exactly one JSON object β€” nothing else
+ stdout = result.stdout.strip()
+ payload = json.loads(stdout)
+ assert payload["status"] == "ok"
+ assert "noisy" not in stdout
+ # The noise landed on stderr instead
+ assert "noisy" in result.stderr