Check reference
Use this page to look up options, configuration, API examples, and limits. For everyday commands, see Check a live browser or saved recording. For a first website check, start with the tutorial.
Setup diagnostics
Section titled “Setup diagnostics”vibium ready # Selected browser and configured AIvibium ready ai --json # Require AI readiness; no browser neededUse ready for initial live setup and ready ai for archive-only checks.
AI diagnostics test configuration and a provider tool round-trip, with up to
two model requests. Browser diagnostics check the installation without
launching a browser. Neither command tests your application’s acceptance
claims.
Plain ready allows missing AI for direct browser automation; Run and Check
require AI. See Readiness diagnostics for selection, installation
fixes, JSON output, and exit codes.
CLI options
Section titled “CLI options”vibium check "<claim>" [options]| Option | Purpose | Example |
|---|---|---|
| No file option | Check the current live browser | vibium check "the cart contains one battery pack" |
-i, --input | Read a saved recording or trace; no browser launch | vibium check "the order confirmation is visible" -i record.zip |
-o, --output | Save a recording of live verification | vibium check "the cart contains one battery pack" -o verification.zip |
--keep-open | Keep a browser started by Check open after the run | vibium check "https://example.com is up" --keep-open |
--report | Save the verdict and evidence as JSON | vibium check "the cart contains one battery pack" --report verdict.json |
--json | Print the CLI result as JSON | vibium check "the cart contains one battery pack" --json |
--expect | Map the verdict to the exit code for gating | vibium check "the cart contains one battery pack" --expect pass |
--keep-open cannot be combined with --input.
--input and --output cannot be combined. You can combine either one with
--report and --json. The old --record and --trace flags are not accepted.
Paths are relative to the caller’s working directory. Output and report files
must be new and must have different paths; existing files are never replaced.
Provider configuration
Section titled “Provider configuration”Check supports OpenAI, xAI, Anthropic, Google Gemini, OpenAI-compatible servers,
and the local alias. See model providers for native
credentials, endpoint defaults, and shared AI settings. The examples
below retain the OpenAI setup.
Per-call overrides are available as --provider, --model, --ai-base-url, and
--reasoning-effort for live and saved-input checks, and for AI readiness.
SDKs and MCP accept equivalent options. See
override settings for one call.
Site under test
Section titled “Site under test”--base-url names the site a live check runs against, so one claim works in
any environment:
vibium check "checkout completes" --base-url http://localhost:3000vibium check "checkout completes" --base-url "$PREVIEW_URL"The site is opened first unless the current page already shares its origin,
so checking a browser you just used keeps its state. Relative navigation
targets resolve against it, and the model receives it as a trusted line kept
apart from page observations. Navigation is not locked to the origin; login
and payment flows cross domains. SDKs and MCP accept it as baseURL
(base_url in Python). It cannot be combined with --input: a saved
recording has no live site to open. The AI provider endpoint is the separate
--ai-base-url.
For OpenAI, export the provider, a model that supports Chat Completions function tools, and
your API key in the terminal running the CLI. For example, with a key already
available as OPENAI_API_KEY:
export OPENAI_API_KEYexport VIBIUM_AI_PROVIDER=openaiexport VIBIUM_AI_MODEL=gpt-5.6-solexport VIBIUM_AI_REASONING_EFFORT=nonegpt-5.6-sol requires none for function tools through Chat Completions.
VIBIUM_AI_REASONING_EFFORT is optional for the adapter and is forwarded
only when set; choose a value supported by your model. For a model that does
not accept this setting, unset the variable.
For an OpenAI-compatible server:
export VIBIUM_AI_PROVIDER=openai-compatibleexport VIBIUM_AI_BASE_URL=http://localhost:1234/v1export VIBIUM_AI_MODEL='your-tool-capable-model'unset VIBIUM_AI_REASONING_EFFORTOPENAI_API_KEY is optional in compatible mode; if set, it is sent as a Bearer
authorization header to the configured endpoint. The server must support
function tools and max_completion_tokens. Image input support is needed for
the screenshot tool.
Configuration is read by each CLI invocation, so changing it does not require restarting the daemon or browser.
Vibium loads ~/.config/vibium/ai.env for empty AI variables. vibium config init
writes the file if you do not have one:
vibium check "the cart contains one battery pack"Keep the file outside your repository. The tutorial shows how to create it with private permissions.
Results and exit codes
Section titled “Results and exit codes”| Displayed verdict | JSON status | Meaning | Exit code | With --expect pass |
|---|---|---|---|---|
| PASS | passed | Evidence supports the claim. | 0 | 0 |
| FAIL | failed | Evidence contradicts the claim. | 0 | 2 |
| REVIEW | inconclusive | Evidence is insufficient to decide. | 0 | 3 |
| Execution error | No verdict | Configuration, provider, browser, or timeout failure. | 1 | 1 |
--expect pass gates automation on the verdict without JSON parsing. The
result is still printed and --report is still written. REVIEW is not
a pass: it fails the gate (fail closed), with exit 3 so a pipeline MAY retry
it while hard-failing on 2. Exit 1 keeps one meaning with or without the
flag. vibium run accepts --expect completed; NOT_COMPLETED exits 2.
REVIEW is the display word for the inconclusive status: the verdict needs
human attention. It is not a pass. JSON output, reports, SDK results, MCP,
and recordings keep the inconclusive string.
With --json, a completed check prints this CLI envelope:
{ "ok": true, "result": { "status": "passed", "claim": "the changed timezone persists after refresh", "summary": "The new timezone persisted after refresh.", "evidence": [ {"type": "observation", "summary": "The saved timezone remained visible after reload."} ] }}ok: true means the check completed. To require a PASS in automation, add
--expect pass or inspect result.status == "passed". Execution errors
print {"ok":false,"error":"..."}.
An inconclusive result MAY carry a machine-readable reason:
reason | Cause |
|---|---|
action_limit | The action budget ran out before a verdict. Retry with a narrower claim. |
insufficient_evidence | The evidence could not decide the claim. |
safety_stop | Safe verification was not possible (credentials, purchases, irreversible actions). |
archive_missing_evidence | The saved recording lacks the needed evidence. |
The verifier reports its own reason; the loop stamps action_limit. PASS and
FAIL never carry a reason. Run results use action_limit,
missing_information, and safety_stop on not_completed.
--report writes the inner result object, without ok or result. Inspect
status at the top level of that file. An execution error leaves no verdict
report. Language APIs also return the result directly and raise exceptions for
execution errors.
Live browser and recording behavior
Section titled “Live browser and recording behavior”Live checks support local Chrome and Firefox. They reuse the existing Vibium
session and selected page. When no browser exists, the CLI starts one and
closes it after recording finalization, including on FAIL, REVIEW, or an
execution error. --keep-open keeps that newly started browser open instead.
A browser already running before Check is always preserved. The ownership
check, launch, verification, and cleanup are serialized in the daemon; its
presence alone does not count as an existing browser. The daemon remains
available for subsequent commands under its normal idle timeout.
Keep the same VIBIUM_SESSION value throughout a workflow. The verifier can
interact with the page and does not restore its starting state.
Recording is optional. Console and network observation tools need an active recording; without one, they report that the evidence is unavailable.
When no recording is active, --output starts one with screenshots and browser
actions, then saves and stops it when Check finishes. It saves available
evidence even if verification encounters an execution error. Video is included
when the browser supports it (Firefox 154+ produces WebM). It is finalized
before the browser closes. Chrome currently records without video.
When recording is already active, --output exports the entire current
recording chunk, including actions before Check. It leaves the ongoing
recording, open groups, video track, and original destination intact. The
export has no continuous video file. Choose a destination different from the
active recording’s path.
Saved recording and trace support
Section titled “Saved recording and trace support”--input accepts Vibium recordings and Playwright traces in trace format
version 8. This is a trace format version, not a Playwright package version.
Other formats and malformed archives return execution errors.
Archive verification uses read-only tools. It does not launch a browser, replay actions, modify the source ZIP, or create a new artifact by default. The verifier can inspect recorded actions, DOM snapshots where present, screenshots, network summaries, console events, and earlier Check groups. The entire archive is not automatically sent to the provider.
Missing evidence can produce REVIEW. An earlier PASS is an assessment to examine, not proof. An archive describes its recorded run and cannot establish what a later deployment or live session does.
Run limits
Section titled “Run limits”- Claims must be nonempty and at most 4,000 bytes.
- Each run has a three-minute budget and at most 24 model-selected actions.
- Text and image payloads are bounded; truncated text is marked.
- Exhausting the action limit returns REVIEW with reason
action_limit. A timeout returns an error. - Browser polling or recording cleanup can take additional time after a timeout.
MCP and language APIs
Section titled “MCP and language APIs”Configure the verifier environment before starting the MCP server or SDK runtime. These surfaces read configuration in the Go process; restart that runtime after changing its environment. All invoke the same verifier adapter, result validation, and bounded tool loop used by the CLI.
MCP exposes vibium_check:
{"claim":"changing my timezone persists after refresh","page":"existing-context-id"}Omit page to use the active page. To inspect an archive, pass
{"claim":"the order confirmation is visible","record":"/absolute/path/record.zip"}.
record and page cannot be combined. Archive mode does not start a browser.
Use existing recording tools around live MCP checks to save their evidence.
JavaScript and TypeScript
Section titled “JavaScript and TypeScript”import { browser } from 'vibium';const bro = await browser.start({ headless: true });const page = await bro.page();await page.go('http://localhost:3000/account');await page.context.recording.start({ path: 'verification.zip', video: false });try { const result = await page.check('changing my timezone persists after refresh'); console.log(result.status, result.evidence);} finally { await page.context.recording.stop(); await bro.stop();}// Standalone archive inspection: no browser installation or launch.const recorded = await browser.check('the order confirmation is visible', { record: './record.zip' });The synchronous API has the same methods via vibium/sync; omit await.
Browser.check() uses the active page, while Page.check() pins that Page.
Both also accept { record: './record.zip' }, which selects read-only evidence
instead of inspecting their live browser.
Python
Section titled “Python”from vibium import browserbro = browser.start(headless=True)try: page = bro.page() page.go('http://localhost:3000/account') result = page.check('changing my timezone persists after refresh') print(result['status'], result['evidence'])finally: bro.stop()recorded = browser.check('the order confirmation is visible', record='./record.zip')For async Python, import from vibium.async_api and await browser operations
and Check. Use page.context.recording.start() / .stop() around a live
check to save its evidence.
Browser bro = Vibium.start(new StartOptions().headless(true));try { Page page = bro.page(); page.go("http://localhost:3000/account"); CheckResult result = page.check("changing my timezone persists after refresh"); System.out.println(result.status());} finally { bro.stop();}CheckResult recorded = Vibium.check( "the order confirmation is visible", CheckOptions.builder().record(Path.of("record.zip")).build());Import com.vibium.*, com.vibium.types.*, and java.nio.file.Path. Use
page.context().recording() for live recording. A Browser or Page can also
call check(claim, options) with an archive. Returned statuses and errors
have the same meaning across all language APIs.
Recording privacy
Section titled “Recording privacy”Export masks credential fields and known credential values in textual recording events, including earlier actions, console observations, and raw BiDi events. Credentials from verifier configuration are registered for redaction without being stored as verifier metadata. Sensitive form fields cause visual artifacts for that recording to be omitted, including video; the ZIP retains the action timeline and a privacy notice. Existing recordings remain active, and export never changes browser form values.
This is a defined redaction policy, not universal secret detection. Arbitrary secrets in unrecognized application content or opaque images cannot be reliably identified. Prefer test data and inspect artifacts before sharing.