High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Agent CLI Test Blueprint — Setup/Server/Config
Reusable test plan for validating the agent-facing UX of the setup, server,
and configuration commands. Run by spawning a fresh general-purpose agent
with only the skill (./skills/pinchtab/SKILL.md) and the built binary
(./pinchtab) — no other context.
The agent should execute each scenario, capture output, and report:
- What worked.
- What failed (exact command + error).
- What was confusing or required guesswork beyond the skill.
- Suggestions to make commands more agent-friendly.
Preconditions
./pinchtabexists and is executable../skills/pinchtab/SKILL.mdis readable.- No pinchtab server currently running on the configured port.
Scenarios (run in order)
Phase 1 — Read-only inspection (no side effects)
./pinchtab(bare) — expect a hint screen showingserver stopped,allowedDomains,idpi, plus "Next steps" / "Configure" hints../pinchtab --help— confirm command list is discoverable../pinchtab config— expect a Config overview + "Change config:" hints../pinchtab security— expect Security checks + recommended-defaults summary + "Change security:" hints../pinchtab daemon— expect Daemon overview + "Manage daemon:" hints../pinchtab daemon --json— expect parseable JSON withinstalled,runningkeys../pinchtab config get server.port— expect plain value on stdout../pinchtab config show— expect structured config output.
Phase 2 — Background server lifecycle
./pinchtab server --background— expect JSON on stdout withpid,url,token,logFile,pidFile. Capture all four../pinchtab(bare again) — expectprotected listener; bare status must not send the API token to identify the listener../pinchtab health— expect first lineok, then "Next steps" hints.PINCHTAB_SESSION= ./pinchtab health --json— expect JSON; verify it contains asecurityblock withlevel,allowedDomains,idpiEnabledwhen using the full configured API token rather than an agent session.
Phase 3 — Sessions + browse end-to-end
./pinchtab session create --agent-id testbot— capture the session token from stdout (must be a single line, just the token). Stderr must be empty (no hints).export PINCHTAB_SESSION=<token>then./pinchtab nav https://example.com --snap— expect snapshot../pinchtab text— expect page text from example.com.
Phase 4 — Stop and verify
./pinchtab server stop— expect "Stopped background server (pid …)"../pinchtab— expectserver stoppedagain, matching the Phase 1 baseline.
Phase 5 — Config introspection & safe mutations
Server can be stopped or running; if you need it for these checks, restart
with ./pinchtab server --background.
./pinchtab config path— expect a single line with the config file path../pinchtab config validate— expect a "valid" message and exit 0../pinchtab config get nonexistent.path— expect a clear error and non-zero exit.printf 'n\n' | ./pinchtab config set server.port abc— expect a validation warning on stderr, the messageaborted: value not saved, and exit code 1. Verify port is unchanged afterwards.- Round-trip a safe value:
- Read original:
./pinchtab config get instanceDefaults.maxTabs(record value). - Set new:
./pinchtab config set instanceDefaults.maxTabs 25. - Verify:
./pinchtab config get instanceDefaults.maxTabs. - Restore:
./pinchtab config set instanceDefaults.maxTabs <original>. - Verify again.
- Read original:
./pinchtab config schema— expect a URL../pinchtab config schema --print— expect JSON Schema output (truncate to first 5 lines).
Phase 6 — Session lifecycle
Server must be running.
./pinchtab session create --agent-id agentA— capture token A../pinchtab session create --agent-id agentB --label "second"— capture token B../pinchtab session list— expect both sessions visible.PINCHTAB_SESSION=<tokenA> ./pinchtab session info— expect agent IDagentA.- Revoke session B: extract its session ID from
session listand run./pinchtab session revoke <id>. Verify withsession listit's gone (or marked revoked).
Phase 7 — Error cases & edge cases
- With server stopped:
./pinchtab health— should fail clearly, not hang. - With server stopped:
./pinchtab nav https://example.com— should auto-start the server, wait for the browser instance to come up, and return success with a tab id on stdout. Exit code 0. - With no PID file:
./pinchtab server stop— expect a clear "no PID file" error, non-zero exit. - Start once:
./pinchtab server --background. Then immediately try./pinchtab server --backgroundagain — expect a "server already running (pid X); stop with: pinchtab server stop" error. - Stop the server, then run
./pinchtab daemon --json— verify JSON shape and thatrunningis false.
Phase 8 — YOLO background flow
- Stop any running server first.
./pinchtab server --background -y— expect JSON same shape as scenario 9; the "YOLO" message goes to stderr../pinchtab(bare) — expectprotected listener; bare status must not send the API token to discover guards-down state.PINCHTAB_SESSION= ./pinchtab health --json | jq '.security.guardsDown'(or grep) — expecttruewhen using the full configured API token rather than an agent session../pinchtab server stop— clean up.
Things to deliberately NOT do
- Do not run
security up,security down,config set,config patch,config init,daemon install,daemon uninstall, or anything else that mutates the user's persistent config or system. - Do not delete
~/.pinchtab/or any of its contents. - If a step fails, do NOT try to "fix" the user's environment — log the failure and continue to the next scenario.
Report format
For each scenario, report:
### Scenario N — <name>
Command: <exact command>
Exit code: <int>
Stdout (verbatim, trimmed):
<output>
Stderr (verbatim, trimmed):
<output>
Verdict: pass | fail | confusing
Notes: <one or two sentences about what was unclear or unexpected>
End with a "Top issues" section listing the three biggest agent-friendliness gaps you hit, in priority order.