MCP & CLI

One engine, two front doors. The jevitate CLI is for people and scripts; the MCP server is a convenience for agents that could run the CLI anyway. Every CLI command is reachable over MCP and every MCP tool from the CLI, except a short list kept human-only on purpose.

The CLI

Without --json, a command prints a short human summary: the verdict, key counts, each finding with its fingerprint, where the result is, and a next: line. With --json, stdout is exactly one line: the {v, ok, data} envelope, or {v, ok: false, error: {code, message}}. The exit code is the same either way (exit codes).

Every flag of every command is in the generated reference, docs/cli.md, or jevitate <command> --help.

Set up an agent: jevitate init

jevitate init                               # keys, skills, MCP registration, .jevitate/
jevitate init --dry-run                     # show what it would install or register; write nothing
jevitate init --uninstall                   # remove the skill files and marked blocks init installed (--force for edited ones)
jevitate init --claude-md                   # also keep a pointer block in the project's CLAUDE.md
jevitate init --codeowners "@acme/qa"       # a marked CODEOWNERS block for the approval files
jevitate init --skip-keys                   # also: --skip-skills, --skip-mcp, --skip-project
jevitate init --replace-keys                # prompt for new keys even when some are stored
jevitate ai status                          # each key, its provider and source, checked live (exit 2 if bad)
jevitate ai status --no-verify              # offline / CI: presence and source only
jevitate init --targets claude-code,codex,cursor
jevitate mcp --print-config claude          # or cursor | codex | json: print the snippet only

init installs skills into every agent runtime it detects, registers the MCP server, and creates the repo's .jevitate/. A file or entry you edited is never overwritten without --force; on a conflict, init prints the snippet instead. Run without a terminal, it never prompts for keys: it reports which are missing and still exits 0.

Keys are checked with their provider by one live, non-billable auth call: valid, invalid, unreachable or missing, plus a flag for a key that looks like another provider's. ai status exits 2 when a key is invalid or could not be checked, and ai setup never stores a key that fails the check. Runs that use the live AI check once at startup and stop with E_AI_SETUP_REQUIRED (exit 64) on a rejected key. Offline or in CI, pass --no-verify to ai status, ai setup or init, and set JEVITATE_NO_KEY_VERIFY=1 for runs. A key value is never printed, logged or sent to a model. Judgment (Jev) runs on either TYPESAFE_API_KEY or OPENROUTER_API_KEY (0.8.0); with both, the TypeSafe key wins, and --jev-provider typesafe|openrouter (MCP jevProvider, env JEVITATE_JEV_PROVIDER, the flag winning over the env var) pins one. ai status shows the route, key and model, for example judgment: ready via OpenRouter (model ~typesafe/jev-latest; no TypeSafe key set).

The skills: jevitate-getting-started (the entry point), jevitate-explore (run a bounded mission), jevitate-mission-scope (read a diff and decide what to test), jevitate-run-journey, jevitate-record, jevitate-demo, jevitate-verify-fix, jevitate-ci-check, jevitate-test-campaign (plan and run a whole-release test campaign), jevitate-ux-review, jevitate-load-test and jevitate-sources. A prompt to paste for each runtime is on the homepage.

The MCP server: jevitate mcp

A stdio server that exposes an allowlist of domain tools and nothing else. The served tool list is checked against the allowlist in @jevitate/mcp-facade, and a parity test fails the build when a CLI command or flag has no MCP decision.

Not reachable over MCP, on purpose

How the tools behave

• A tool that mirrors a command takes typed, closed arguments named after its flags (--storage-state → storageState), runs that command in process, and returns {exitCode, data}: the command's own envelope data and exit code.
• Exit 0, 1, 3, 4 and 5 are answers (1 = defects found or still reproduces; 5 = a self-heal revision is pending review, never a pass — run_journey returns it as exitCode: 5). Exit 2 (proved nothing) and every refusal come back as MCP errors, never a pass: {error: "invalid_args" | "refused", code, message, exitCode}.
• Every path argument must resolve inside the project the server runs in or ~/.jevitate/. Operator-only settings are never MCP arguments: shell hooks, the browser binary and switches, which environment variable a secret is read from, server-log sources, and store directories. Set those in ~/.jevitate/targets.json or on the CLI.
• A run on one Journey, finding or suite returns when it is done. Open-ended exploration of a promoted target is queue and poll: queue_exploration → run_queued_missions (or jevitate mission run) → get_mission_result.
• Tools that launch a browser take an extension array of unpacked extension directories and the resource limits maxBrowsers and maxBrowserMemory; --ignore-host-load stays the operator's call.

geolocation, replyQuietMs and successWhen (including each) are MCP arguments where the CLI flag applies.

Mid-run secret commands are operator-only

A cmd: secret source and --allow-secret-cmd run a command on this machine, so they are never an MCP argument or a suite option. Set them on the CLI.

Signal triage is operator-only

jevitate logs triage and --log-triage have no MCP tool or argument. Sending log text to the judgment model is the operator's decision, so a request never turns it on. The operator opts a target in with "logTriage": true in ~/.jevitate/targets.json (queued and MCP runs) or on a check suite item or target. MCP callers then get relatedLogs on each defect in every result and in get_report. run_campaign takes the safety and media options; log sources, hooks and triage stay on the CLI.

Sweeps, tags and persona sessions (0.8.0)

jevitate sweep --targets <file.tsv|file.json> runs many explore missions with --concurrency, --resume, --stop-on-env-failure and --out; MCP run_sweep mirrors it. --tag key=value stamps a run, and MCP run tools take a tags object. jevitate login mints a persona session and is CLI-only: it reads the operator's credential environment variables, so no MCP tool exists for it. See Sweeps & Personas.

0.9.0: heal proposals, pinned browser

journey run and check take --self-heal with --changes / --change-note and the --heal-max-* budgets, and a heal exits 5 (healed-pending-review). journey promote <id> --proposal <pid> accepts a proposal and --reject-proposal <pid> --reason rejects it (over MCP: promote_journey with proposal or rejectProposal + reason). jevitate install-browser installs the Chromium revision jevitate pins into the shared browsers directory without removing other revisions; jevitate browser-path prints it (--json, --export); jevitate doctor reports a missing pinned browser. jevitate sweep adds --no-host-starved-retry, and jevitate login --api is CLI-only.

0.10.0: Journeeze, outcomes, step ids, locator health

Four MCP tools are new: export_catalog_bundle, publish_to_journeeze, draft_job_outcomes and locator_health. review_journey takes stale, and run_check takes maxBrittleSteps. connect_journeeze is on the forbidden list: entering an upload key is a person's act at a terminal (jevitate connect journeeze), and no key ever passes through a model or an MCP argument. publish_to_journeeze takes none; jevitate resolves the key itself (its secret store, or JOURNEEZE_UPLOAD_KEY in CI) and never returns it. export_catalog_bundle writes only inside the project. The pr-review approval channel is never one a caller can set: no MCP argument grants it. Node 22 or later is required. See Catalog & Sign-off and locator health.

0.11.0: anchors, preflight, slow steps

Two MCP tools are new: journey_anchor_add and journey_anchor_remove. New arguments: lint_journey fix, journey_anchors suggest, run_journey stepResponseTimeoutMs, run_campaign skipPreflight, publish_to_journeeze productName and verify_fix env. verify_fix refuses allow: an MCP caller never names origins, so verify-fix --allow stays CLI only. An adversarial run's transcript reads a finding a blocked write caused as an environment fault. See anchors, campaign preflight, slow steps and verify-fix.

0.12.0: review sheet and step labels

No MCP tool is new. review_journey returns the same JSON sheet with additive fields (attention, per-step checks, file, anchors and locator, summary.intent, proof.endStateText). journey review --full and journey promote --full are CLI only, and so is journey migrate --labels (a repo rewrite that replays the app and that the operator runs and commits). Upload fixtures outside the project, or sensitive ones, are refused over MCP as on the CLI. See the review sheet, step labels and upload fixtures.

0.13.0: anchors on promoted Journeys, sweep fixtures

No MCP tool is new. journey_anchor_add, journey_anchor_remove and lint_journey with fix now work on a promoted Journey; the add and remove results carry needsReapproval and reapproveCommand, and the re-approval stays a person's step. run_sweep takes fixture (the sweep-wide upload fixture, confined like every upload fixture). The sweep browser launch flags (--browser-arg, --browser-executable, --browser-channel, --extension, --max-browsers, --max-browser-memory, --ignore-host-load) are CLI only, the operator's setting, as on every browser-driving command. See anchors on a promoted Journey and sweeps.

0.14.0: scope regions, navigation guard, promotion-ready

Two MCP tools are new: catalog_draft and journey_link. New arguments: run_exploration.scopeRegion (a list of descriptors; adversarial, coverage and exploratory only), run_exploration.blockOffAllowlistNavigation (mission sessions only), journey_anchor_add.region, review_journey.strict and catalog_status.strict. A suite item takes scopeRegion and blockOffAllowlistNavigation. See scope regions, the navigation guard and promotion-ready.

0.15.0: http checks, allowed origins, recorded fixtures

No MCP tool is new. author_journey takes fixtures and fixtureIdentity (recorded on the Journey as metadata.fixtures) and maps allowWrites; like run_exploration it omits the backend-log flags. http: checks work in MCP success strings. run_journey and verify_journey take no allow argument: they use the Journey's recorded metadata.allowedOrigins (the CLI's journey run|verify --allow adds more), and they reuse the recorded fixtures with no argument. See split-origin apps, http checks and recorded fixtures.

Queue missions from the CLI

mission queue, mission run and mission result use the same queue as MCP (~/.jevitate/missions/), so what one queues the other sees.

# register a target: UNPROMOTED, so nothing can be queued against it yet
jevitate mission target add spa --name "App" \
  --authorized-origin http://127.0.0.1:5193 --api-origin http://127.0.0.1:18582 \
  --base-url http://127.0.0.1:5193/settings
jevitate mission target promote spa          # a human act: only promoted targets are queueable

jevitate mission queue spa --strategy coverage --route '/settings/**'   # what queue_exploration does
jevitate mission run --once --real           # drain what is queued now (--watch keeps polling)
jevitate mission result <missionId>          # what get_mission_result reports; exits with its code

• Queueable strategies: goal-based (a goal and a success check), coverage, exploratory, adversarial and feature. Usability is not queueable; run it directly.
• A mission reaches only its target's --authorized-origin plus its --api-origins, and the target is re-checked (promoted only) when the mission runs.
• A queued mission may ask for media next to its result (--record-video, --evidence-video, --screenshots) and a --persona name from ~/.jevitate/targets.json; never a path. Queued missions stay headless.
• Without --real or --fake-ai, model-driven missions stay queued (reported as skipped) and only feature missions run.
• mission result exits with the result's own code (0 clean · 1 defects · 2 broken run · 3 hang · 4 intermittent); a mission still queued or running exits 2.

The inbox, from the CLI and in jevitate ui

When an agent needs a person (an approval, a value or a review) it queues an inbox item. The inbox commands call the same handlers the MCP server does, over ~/.jevitate/inbox:

jevitate inbox list                  # pending items (list_incoming)
jevitate inbox show <id>             # an item's redacted thread (get_thread)
jevitate inbox command <id>          # poll it as the agent does (get_command)
jevitate inbox command <id> --reveal # consume the human's unread input and print it
jevitate inbox health                # pending count, oldest age, build (get_site_health)
jevitate ui                          # where a person approves, rejects or answers

• inbox command keeps get_command's burn-after-read rule: if a person handed back input that hasn't been read, it refuses (E_INBOX_INPUT_PENDING, exit 64) and consumes nothing; --reveal consumes it and prints it.
• Approving or cancelling stays human-only: inbox approve / inbox cancel (and MCP approve_action / cancel_command) always refuse.
• jevitate ui is a local, single-user dashboard on http://127.0.0.1:4180 (--port to change it). It binds to loopback only and mints a per-session capability token, so a stray browser tab can't drive approvals.

Record by demonstration

jevitate record opens a headed browser on an authorized origin, lets you drive the flow, and captures it into a Recording. The authorized-target guard runs before any browser opens. Press Enter (or Ctrl+C) to end the take; it is saved either way.

jevitate record \
  --url http://localhost:3000 \
  --intent "Check out with a saved card" \
  --retro "The confirm button moved below the fold" \
  --allow http://localhost:3000 --allow https://checkout.stripe.com

• --url <url>: the start URL (must be an authorized origin).
• --intent <text> / --retro <text>: your framing and an optional retrospective, carried into the Recording.
• --allow <origin>: authorized origins (repeatable). It replaces the default (the URL's own origin), so include that too.
• --headless: run headless. The default is headed, since a record session is a live demonstration.
• --out <dir>: where the Recording goes (default .jevitate/logs/<date> in the project).

A recorded take is one step short of a Journey. See Journeys.

Distributed sources

A source is a git repo of shared Journeys. Adding one clones it and pins its HEAD; it never trusts anything implicitly. Trust and Terms-of-Use acceptance are separate, explicit acts, and the pin only advances on update.

# register a remote source (clone + pin its HEAD). --accept-tou
# acknowledges its declared Terms of Use so its Journeys can run
jevitate source add acme https://github.com/acme/jevitate-journeys.git --accept-tou

jevitate source list                 # registered sources + which Journeys you trust
jevitate source pull acme            # fetch new refs, never advances the pin
jevitate source update acme          # the only command that advances the pin
jevitate source trust acme checkout  # trust one Journey, bound to its content hash
jevitate source run acme checkout    # run a trusted remote Journey through the run-gate
jevitate source remove acme          # drop the clone + lock entry

Publishing a Journey to a source

jevitate journey publish shares a promoted Journey into a registered source, always on a new publish/<id> branch. It opens a PR via gh when available, or prints push instructions.

# --to is required. The Journey must be promoted first
jevitate journey publish checkout --to acme

# declare the origins it is authorized for (default: derived from its
# navigate steps) and optionally publish under a different id
jevitate journey publish checkout --to acme \
  --declare-origin https://acme.test \
  --as acme-checkout

Publishing fails closed on an unregistered source, an unpromoted Journey, a Journey that declares no origins, a materialized (non-redacted) secret value, or an origin the steps touch but the declarations don't cover.

Usability review

Findings on whether a user got the job done and where the experience got in the way. Each one is a claim code verified (a guard probe, a conflict with your product facts, or friction the run hit); Jev only categorizes and grades. Advisory: a finding never sets a non-zero exit.

# offline: review a saved Recording. --app-class calibrates the rubric
jevitate ux ./checkout.recording.json --app-class consumer --real

# optional persona + the job the flow pursues, for sharper relevance
jevitate ux ./checkout.recording.json --app-class admin \
  --persona "first-time buyer" --job "check out with a saved card" --real

# live: run usability as an exploration strategy (needs --goal + --app-class);
# --probe-guards opts in to the fail-safe destructive-control probe (prefer staging)
jevitate explore --url http://localhost:3000 \
  --strategy usability --goal "check out" --app-class consumer \
  --product .jevitate/product.json --probe-guards --real

• --app-class is required on both paths (e.g. consumer, admin, internal).
• ux --persona <text> is a usability persona for calibration. It is not explore --persona, which runs a mission once per signed-in session.
• On the live path, --success checks decide whether the job was done, as on a goal run.
• --product <file> (default .jevitate/product.json) lists plans, prices, trials and each page's intended next step; --polish rewrites recommendations with one generation call.

See Usability Review and Report Schema.