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@v1 with offline: true.
  • The proxy: vericto-proxy mcp in 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

  • --offline or VERICTO_OFFLINE=1: always offline, in CI too, even if a key is set.
  • Outside CI, with no API key, no vericto login and no OIDC token: offline on its own, and it says so on stderr.
  • In CI (CI, GITHUB_ACTIONS, GITLAB_CI, BUILDKITE, JENKINS_URL and other CI variables), a missing credential stays exit 3: a pipeline whose secret went missing does not quietly fall back to fewer rules. Pass --offline to choose it.
  • A present but invalid key is exit 3 and an unreachable backend is exit 4: neither ever switches to offline. .vericto.toml cannot choose the mode: a committed offline key is rejected (exit 2).

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.

CodeMeaning
0Nothing at or above --fail-on (block by default)
1A finding at or above --fail-on
2Usage error: bad arguments, an unreadable file or an option that needs a workspace
3Auth or config error: online, or in CI with no credential and no --offline
4Backend 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 with api-key, a job-level VERICTO_API_KEY or oidc; 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, exit 3. A rejected credential or an unreachable API is never replaced by an offline check.
  • The mode output is online or offline, and the job summary has a Mode row.

@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:

OfflineWith a workspace
Rulesthe 42 standard rules, at their default severitiesyour workspace's rules: the standard ones with your overrides, plus your custom rules
Business policies, sensitive columns and masking, agent allowlistsnoyes
Historyno record anywhereevery CLI check is recorded, with the commit, the run and the actor; the proxy and the MCP server record every query
Dashboardnorules, history and audit; for the proxy and the MCP server, the kill switch too
CLI resultone per file, with its strongest findingone per statement, at its line
Signed receipts (--receipt)no (exit 2)yes
Networknone: the SQL never leaves the machinethe 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=1 or DO_NOT_TRACK=1 in 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 --format other than text, 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"