Offline mode: Vericto with no account
Check SQL with Vericto's standard rules on your machine or your CI runner: no account, no API key and no network. The CLI, the GitHub Action and the proxy, with the real output of CLI 2.3.0.
What it is
In offline mode, Vericto evaluates SQL on your machine with the engine built into the binary. No account or API key is needed, no network request is made, to Vericto or anyone else, and the SQL never leaves the machine. CLI 2.3.0 embeds vericto-engine 5.1.0 and its 42 standard rules at their default severities: Critical and High block, Medium flags (FLAGGED) and Low is monitored (MONITORED).
It is a baseline gate: it answers "is this SQL obviously dangerous?". It is not your workspace's policy and it leaves no record that a check took place; that is what online mode is for (see What a workspace adds). It is in three places:
- The CLI:
vericto check --offline, in your terminal, in a pre-commit hook or in any CI. Linux, macOS and Windows (x64 and ARM64). - The GitHub Action:
vericto/check-sql@v1withoffline: true. - The proxy:
vericto-proxy mcpin local mode and the TCP proxy with no workspace, on the built-in rules.
The CLI: vericto check --offline
Install the CLI (Homebrew, npm, Scoop, the shell or PowerShell installer, Docker or the release binary: see Install & authenticate) and pass --offline, or set VERICTO_OFFLINE=1:
# No account, no network: the standard rules at their default severities
vericto check --offline migrations/*.sql
vericto check --offline db/migrate/ # every *.sql under it, recursively
git show :db/schema.sql | vericto check --offline - --dialect mysql
VERICTO_OFFLINE=1 vericto check db/migrate/
# Zero-install, with Node 18+
npx @vericto/vericto-cli check --offline migrations/*.sql
The vericto check options work as they do online: --dialect (postgres by default, mysql, oracle, mssql, snowflake and sqlite), --fail-on, --format, --output, --quiet, --monitor, --baseline, inline -- vericto:ignore[...] comments, --changed and --since (a local git diff). vericto:ignore comments count in files; in --sql and stdin only with --allow-inline-ignore (CLI 2.3.0), because nobody reviews that text and the agent being checked may have written it. --receipt, --oidc, --allow-degraded and --allow-unsanitized need a workspace: offline, they are refused with exit 2 rather than ignored.
When it is automatic
--offlineorVERICTO_OFFLINE=1: always offline, in CI too, even if a key is set.- Outside CI, with no API key, no
vericto loginand no OIDC token: offline on its own, and it says so on stderr. - In CI (
CI,GITHUB_ACTIONS,GITLAB_CI,BUILDKITE,JENKINS_URLand other CI variables), a missing credential stays exit3: a pipeline whose secret went missing does not quietly fall back to fewer rules. Pass--offlineto choose it. - A present but invalid key is exit
3and an unreachable backend is exit4: neither ever switches to offline..vericto.tomlcannot choose the mode: a committedofflinekey is rejected (exit2).
The CI profile: DDL in a migration is FLAGGED
Since CLI 2.3.0, the schema change rules (VERICTO-010, 013, 015 to 019, 094 and 099: DROP TABLE, ALTER…) are capped at FLAGGED only in migration files, because people review a migration in a PR. A file is a migration if it is under a migrations/, migration/ or migrate/ directory, is named like a Flyway (V2__name.sql) or golang-migrate (1_name.up.sql) file, or its path is in migration_paths in .vericto.toml. --sql, stdin and other files are checked like runtime SQL: DDL blocks, and the CLI explains on stderr how it recognises migrations. TRUNCATE (VERICTO-011) and DROP SCHEMA / DATABASE (VERICTO-012) always block, in a migration too. With --fail-on block, the default, a migration with only DDL exits 0 and shows the finding; to fail on it, use --fail-on flag. Online the cap still covers every file, and TRUNCATE and DROP SCHEMA / DATABASE until vericto-eval 2.12.0 is deployed.
A file with several statements reports the finding with the strongest action: in a migration with DROP TABLE a; DELETE FROM sessions; the DROP is flagged, but the WHERE-less DELETE blocks, so the file is BLOCKED and the run fails. If an AI agent uses the result to decide whether to run SQL, pass the SQL with --sql (or on stdin), never as a migration file; or use the local MCP server, which blocks DDL at the rule's severity (see The proxy with no account).
Formats and exit codes
--format takes text (the default), json, sarif, gitlab-codequality and gitlab-sast. Every offline result says where it came from: mode: offline and the engine version in the text summary, "mode": "offline" and "engine_version" in JSON, a properties bag (mode, engine and ruleset version) in SARIF, a note on each finding in the GitLab reports, and Vericto (offline) as the title of GitHub annotations. The ruleset is standard@engine-5.1.0.
| Code | Meaning |
|---|---|
0 | Nothing at or above --fail-on (block by default) |
1 | A finding at or above --fail-on |
2 | Usage error: bad arguments, an unreadable file or an option that needs a workspace |
3 | Auth or config error: online, or in CI with no credential and no --offline |
4 | Backend or network error, online only (never switches to offline) |
Offline, each file gets one result with its strongest finding, at line 1. Online, each statement is reported at its own line.
Pre-commit hook
With pre-commit, the vericto-check hook runs vericto check --offline on the *.sql files each commit changes, with no account, API key or network. pre-commit installs @vericto/vericto-cli once, and that install checks the binary's SHA-256. A BLOCKED statement fails the commit; FLAGGED and MONITORED ones are shown and the commit goes through.
# .pre-commit-config.yaml
repos:
- repo: https://github.com/vericto/vericto-cli
rev: v2.3.0
hooks:
- id: vericto-check
# args: [--fail-on, flag] # also fail on FLAGGED (schema changes)
Real output
This is what the published CLI, npx @vericto/vericto-cli@2.3.0, printed on macOS on November 15, 2026, for two sample migrations:
-- migrations/0001_create_users.sql
CREATE TABLE users (id bigint PRIMARY KEY, email text NOT NULL);
-- migrations/0002_cleanup.sql
-- Remove the legacy table and old sessions
DROP TABLE legacy_users;
DELETE FROM sessions;
vericto check --offline migrations/ exits 1: the DELETE without WHERE blocks the file, which reports its strongest finding.
$ vericto check --offline migrations/
note: offline mode: 42 standard rules at default severities, engine 5.1.0. Custom rules, overrides, sensitive columns, allowlists and the audit trail apply online only.
✖ migrations/0002_cleanup.sql BLOCKED VERICTO-001 critical
DeleteStmt > WhereClause = NULL
fix: DELETE FROM sessions WHERE id = $1
1 blocked · 1 allowed · 0 flagged · 0 monitored (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
✖ Vericto blocked 1 statement (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
✖ migrations/0002_cleanup.sql BLOCKED VERICTO-001 critical
DeleteStmt > WhereClause = NULL
fix: DELETE FROM sessions WHERE id = $1
This is Vericto enforcing a rule — the exit code is intentional, not a crash.
To allow a finding on purpose, add an inline comment on the statement:
-- vericto:ignore[VERICTO-001] <reason> (a reason is required)
$ echo $?
1
A migration with only DROP TABLE legacy_users; is FLAGGED and exits 0; with --fail-on flag, it exits 1:
$ vericto check --offline migrations/0003_drop_legacy.sql
note: offline mode: 42 standard rules at default severities, engine 5.1.0. Custom rules, overrides, sensitive columns, allowlists and the audit trail apply online only.
! migrations/0003_drop_legacy.sql FLAGGED VERICTO-010 critical
DropStmt
fix: Use a versioned migration tool (Flyway, Prisma Migrate, Alembic, Rails migrations)
0 blocked · 0 allowed · 1 flagged · 0 monitored (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
$ echo $?
0
$ vericto check --offline migrations/0003_drop_legacy.sql --fail-on flag
…
✖ Vericto: 1 statement flagged; failing because --fail-on flag (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
! migrations/0003_drop_legacy.sql FLAGGED VERICTO-010 critical
…
$ echo $?
1
The same statement with --sql is not a migration: it is blocked, exits 1 and the CLI explains on stderr how it recognises migrations (and that a vericto:ignore in --sql needs --allow-inline-ignore):
$ vericto check --offline --sql "DROP TABLE legacy_users;"
note: offline mode: 42 standard rules at default severities, engine 5.1.0. Custom rules, overrides, sensitive columns, allowlists and the audit trail apply online only.
✖ <inline> BLOCKED VERICTO-010 critical
DropStmt
fix: Use a versioned migration tool (Flyway, Prisma Migrate, Alembic, Rails migrations)
1 blocked · 0 allowed · 0 flagged · 0 monitored (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))
…
Inline ignores are not honoured for --sql/stdin input. To allow a finding on purpose, put the SQL in a reviewed file with an inline comment on the statement:
-- vericto:ignore[VERICTO-010] <reason> (a reason is required)
or pass --allow-inline-ignore to honour that comment in --sql/stdin input.
note: VERICTO-010 is schema DDL. It is reported as FLAGGED only in a migration file (under a migrations/, migration/ or migrate/ directory, a Flyway V1__name.sql or a golang-migrate 1_name.up.sql file, or a path in .vericto.toml's migration_paths); --sql, stdin and other files are checked like SQL run against the database.
$ echo $?
1
The first file in JSON (--format json, on stdout):
{
"engine_version": "5.1.0",
"exit_code": 1,
"mode": "offline",
"queries": [
{
"action": "block",
"ast_node_path": "DeleteStmt > WhereClause = NULL",
"file_index": null,
"line": 1,
"rule_code": "VERICTO-001",
"severity": "critical",
"sql_preview": "-- Remove the legacy table and old sessions\nDROP TABLE legacy_users;\nDELETE FROM sessions;\n",
"status": "BLOCKED",
"suggested_fix": "DELETE FROM sessions WHERE id = $1"
}
],
"summary": {
"allowed": 0,
"blocked": 1,
"flagged": 0,
"monitored": 0,
"parse_errors": 0,
"ruleset_version": "standard@engine-5.1.0",
"total": 1
}
}
With no --offline, no credential and outside CI, the CLI says so on stderr before it evaluates:
note: no API key or login found: checking offline with the 42 standard rules (engine 5.1.0). Run `vericto login` to check against your workspace's rules and record the run.
The GitHub Action
vericto/check-sql@v1 (Apache-2.0) wraps vericto check: it downloads a pinned CLI release, verifies its SHA-256 before extracting it, checks the *.sql files the pull request changes and shows the findings in the log, the job summary and as annotations. With offline: true it checks on the runner, with no account or secret. It works on Linux, macOS and Windows runners (x64 and arm64). Save this as .github/workflows/vericto.yml:
on: pull_request
jobs:
vericto:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with: { fetch-depth: 0 }
- uses: vericto/check-sql@v1
with: { offline: true, upload-sarif: false }
To also send the findings to Code Scanning, drop upload-sarif: false and give the job security-events: write (and actions: read in private repositories), as in the full setup.
offline: auto(the default): online withapi-key, a job-levelVERICTO_API_KEYoroidc; offline, with a warning annotation, when there is none. A pull request from a fork gets no secrets, so it checks offline too.offline: false: always online; with no credential, exit3. A rejected credential or an unreachable API is never replaced by an offline check.- The
modeoutput isonlineoroffline, and the job summary has aModerow.
@v1 points to 1.4.0, which installs CLI 2.0.0 by default, with engine 5.0.0. To use another CLI release, pin it with cli-version, for example cli-version: "2.3.0" for engine 5.1.0 and the migration-only DDL cap (latest is not accepted).
The proxy with no account
The same binary, vericto-proxy (AGPL-3.0-only), has two modes that work with no workspace: they use the built-in rules and report nothing, as no event, heartbeat or rule sync leaves the machine. Version 5.0.1 uses vericto-engine 5.0.0 and ships native binaries for Linux, macOS and Windows (install).
vericto-proxy mcp in local mode
An MCP server that lets an AI agent (Claude Code, Cursor, Codex or any MCP client) read a PostgreSQL database through Vericto: the agent gets execute_sql, describe_schema, check_sql and whoami, and never the database credential. It is read-only: execute_sql runs reads only, in a transaction that always rolls back, with row, size and time caps. With none of VERICTO_API_KEY, VERICTO_DATABASE_ID and VERICTO_API_URL set it runs in local mode, and whoami says so: control_plane.mode: "none" and control_plane.ruleset: "built-in".
# A read-only role's connection URL, in a file the agent does not read
mkdir -p ~/.config/vericto && chmod 700 ~/.config/vericto
printf '%s' 'postgres://vericto_agent_ro:…@db.example.com:5432/shop?sslmode=verify-full' > ~/.config/vericto/db.url
chmod 600 ~/.config/vericto/db.url
# The native binary (Linux, macOS), then register it in Claude Code
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/vericto/vericto-proxy/releases/download/v5.0.1/vericto-proxy-installer.sh | sh
claude mcp add vericto-db -- ~/.cargo/bin/vericto-proxy \
mcp --database-url-file ~/.config/vericto/db.url
check_sql evaluates with the same rules and, unlike the CLI, blocks DDL at the rule's severity. Local mode has no masks, agent allowlists, business policies or kill switch: to stop the agent, remove the server from the client or stop the process. Over HTTP (--transport http) it does not start unless VERICTO_MCP_AUTH_TOKENS_FILE lists at least one token: it is never served unauthenticated. Cursor, Codex, Windows and Docker: see Local server.
The TCP proxy with no workspace
Without the three control-plane variables (VERICTO_API_URL, VERICTO_API_KEY and VERICTO_DATABASE_ID), the TCP proxy protects PostgreSQL or MySQL with the built-in rules and reports nothing. It only needs UPSTREAM_HOST:
# PostgreSQL on localhost:5432; the proxy listens on 5433
UPSTREAM_HOST=localhost vericto-proxy
# MySQL on localhost:3306; the proxy listens on 3307
VERICTO_WIRE_PROTOCOL=mysql UPSTREAM_HOST=localhost vericto-proxy
Your application connects to the proxy with the same credentials. A DELETE without WHERE never reaches the database: the client gets a normal SQL error (SQLSTATE 42501 on PostgreSQL). Docker, Kubernetes, ECS and the full configuration: TCP proxy.
What a workspace adds
Offline gives you the standard rules with nothing to set up. Connecting a free workspace adds what depends on an account:
| Offline | With a workspace | |
|---|---|---|
| Rules | the 42 standard rules, at their default severities | your workspace's rules: the standard ones with your overrides, plus your custom rules |
| Business policies, sensitive columns and masking, agent allowlists | no | yes |
| History | no record anywhere | every CLI check is recorded, with the commit, the run and the actor; the proxy and the MCP server record every query |
| Dashboard | no | rules, history and audit; for the proxy and the MCP server, the kill switch too |
| CLI result | one per file, with its strongest finding | one per statement, at its line |
Signed receipts (--receipt) | no (exit 2) | yes |
| Network | none: the SQL never leaves the machine | the SQL goes to your workspace, sanitized if the workspace says so |
Online checks count against the monthly CLI check allowance; offline ones do not. Start free, then run vericto login: it opens your browser and mints a scoped key for the workspace you pick.
The one-time tip (CLI 2.2.0)
Since 2.2.0, after an interactive vericto check that ran offline with no credential and produced a result, the CLI prints one line on stderr, once per user on the machine. This is the real line:
Tip: connect a free Vericto workspace to keep a history of checks and share rules with your team: https://app.vericto.com/register?utm_source=cli&utm_medium=nudge&utm_campaign=first-check&v=2.2.0
It is not telemetry: the CLI makes no request for it and sends nothing. The link only carries the CLI version and campaign parameters, which the site sees if you open it. To remember it showed the tip, the CLI keeps a small marker file next to its config, ~/.config/vericto/connect-nudge-shown ($XDG_CONFIG_HOME/vericto/ when set; on Windows, %APPDATA%\vericto\). Delete it and the tip can show once more. Stdout and the exit code are the same with or without it.
It never shows:
- with
VERICTO_NO_NUDGE=1orDO_NOT_TRACK=1in the environment; - in CI (any of the CI variables the CLI recognizes), so it never needs turning off in a pipeline;
- when stderr is not a terminal, with a
--formatother thantext, or with--quiet; - when a credential is present: an API key,
vericto login, OIDC or a workspace id; - with any other command,
vericto serve --stdio(the SDKs' offline mode) included.
To turn it off on your machine:
# bash / zsh (in your shell profile)
export VERICTO_NO_NUDGE=1 # or DO_NOT_TRACK=1
# PowerShell
$env:VERICTO_NO_NUDGE = "1"