Skip to content

CLI ​

text
portolan <command> [options]

Commands ​

CommandWhat it does
portolan init [dir]Write a config, a policy, and the maps/ and skills/ directories.
portolan mcpServe MCP over stdio for a client to spawn.
portolan serveStart the HTTP and MCP server.
portolan compile <trace...>Compile traces into a new map version.
portolan verifyVerify a map's operations on a fresh session.
portolan export-skillsExport a portolan-<site> skill from a map.
portolan qa <command>Agent-first QA: generate, run, repair, and verify test cases.
portolan bench [suite]Run a benchmark suite from the source checkout.
portolan doctorDiagnose the browser, config, providers, and clients.

Common options ​

OptionMeaning
--config <path>Config file. Default ./portolan.config.json.
--helpShow usage.

Command flags beat the config file, which beats the default.

QA commands ​

CommandWhat it does
portolan qa initWrite config, dirs, skill, and harness wiring.
portolan qa listList cases and their status.
portolan qa planChoose cases affected by the git diff.
portolan qa runRun cases (deterministic; no model).
portolan qa result <run_id>Read a run's typed results.
portolan qa case read <id>Read one case spec.
portolan qa case write <file>Validate and write one case (always draft).
portolan qa generateTurn a spec or a recorded trace into a draft case.
portolan qa repair <case_id>Recover a broken locator from a failed run.
portolan qa verifyReplay cases and promote verified ones.
portolan qa coverageList routes covered by cases.
portolan qa report <run_id>Render a run as json, md, or junit.
portolan qa syncReconcile case files with the local database.
portolan qa doctorCheck config, database, and the browser.
portolan qa mcpServe the QA MCP server over stdio.

Selection flags: --changed, --suite NAME, --case ID (repeatable), --tag TAG, --all. Common flags: --json, --config PATH, --repeat N, --allow-unverified, --base-url URL.

Examples ​

bash
# initialize a project
portolan init ./my-site --site store

# serve MCP over stdio (what a client spawns)
portolan mcp

# serve MCP over streamable HTTP
portolan serve --port 4200

# verify a map against a live site
portolan verify --map maps/store/v1.json --params store.params.json \
  --base-url https://store.example

# export a skill from a map
portolan export-skills --map maps/store/v1.json --out skills

Environment ​

The CLI reads portolan.config.json and these variables:

VariableMeaning
PORTOLAN_CONFIGConfig file when --config is absent.
MAPS_DIRMap directory for portolan mcp. Default maps.
DATABASE_PATHSession and audit database for portolan mcp.
CHROME_PATHChrome binary when chrome is unset.
PORTOLAN_AUTH_TOKENBearer token for a non-loopback serve bind.

See Configuration for every option.

Released under Apache-2.0 · MIT · CC-BY-4.0