CLI reference

By Ohad Krispin, founder of VibeRaven · LinkedIn

The `viberaven` CLI runs with `npx`, so there is nothing to install, and every command below works without an account except `login` and `account`. Pin the version, as in `npx -y viberaven@1.7.8 check`, when you want the same result every time.

npx -y viberaven@1.7.8 --help

Prints every command and flag of the version you run. Or ask your coding agent to "run npx -y viberaven@1.7.8 check and fix what it reports".

Usage

npx -y viberaven@1.7.8 <command> [path] [flags]

[path] is the project folder. It defaults to the current folder.
Flags take a value with a space or with =: --gap rls_disabled or --gap=rls_disabled.
--help prints the full usage, for any command. --version prints the version.
Node.js 20 or newer. In Windows PowerShell, use npx.cmd if npx is blocked.

Commands
Command	What it does	Account
`check`	Lists the launch gaps in the repo	No
`changes`	Lists provider changes that affect the repo	No
`fix`	Applies a safe automatic fix	No
`prompt`, `next`	One finding as a prompt, or the next action	No
`init`	Writes rules for your coding agent	No
`audit`	Groups the Vercel + Supabase evidence	No
`rls-test`	Tests your permissions matrix on the migrations, locally	No
`login`, `account`	Opens an account, reads your plan	Yes
`connect`	Links this folder to your app on viberaven.dev	Yes

check

Reads the repository and prints each finding with its id, file and line, then a verdict. Reads local files only.

npx -y viberaven@1.7.8 check [path] [--json | --format sarif | --markdown] [--quiet] [--base <ref>]

--json: One JSON object: score, scoreLabel, summary, gaps (each with id, severity, title, detail, and guide and testTheApp when there are), providerChanges, artifacts and nextStep.
--format sarif: SARIF 2.1.0 for GitHub code scanning. See CI.
--markdown: A Markdown table for a pull request comment.
--quiet: Only the title and the path:line of each finding.
--base <ref>: Only what changed since <ref>: new, fixed and already there before.

Exit codes: 0 with no blocker, 1 with at least one, 2 when the scan or the --base comparison fails. It writes its results to .viberaven/, and never changes your code.

changes

Matches the dated provider changes in this release against the repo. Reads local files only, writes nothing.

npx -y viberaven@1.7.8 changes [path] [--json] [--strict]

--json: The changes array, with packVersion and reviewedAt.
--strict: Exit 1 when a change affects the repo. REVIEW does not fail it.

Statuses and the full list are on Provider changes.

fix

Applies an automatic fix for one finding from the last check. Without --gap, it lists the findings that have one.

npx -y viberaven@1.7.8 fix [--gap <id>] [--dry-run] [path]

--gap <id>: Applies the fix at once. Typing it is the confirmation; there is no prompt.
--dry-run: Writes a plan to .viberaven/heal-plan.md and changes nothing.

Fixable gaps:
  viberaven fix --gap auth_secret_missing   Auth secret is not configured
  viberaven fix --gap rls_disabled   No RLS policy proof in migrations   (asks first: enabling RLS without policies makes browser reads return no rows until policies exist)
  viberaven fix --gap missing_error_boundary   No error boundary

fix --gap rls_disabled writes a migration that enables RLS with no policies, so browser reads return no rows until you add them. Ask yourself first, as the list says.

Each applied fix prints a JSON result and saves a patch.diff under .viberaven/heal/. Which findings have a fix is listed in the findings reference.

prompt and next

Both read the last check and write nothing.

npx -y viberaven@1.7.8 prompt --gap rls_disabled --no-copy
npx -y viberaven@1.7.8 next --json

prompt --gap <id>: Prints the fix for one finding as a prompt for your agent, then Test the app after the fix: and the test. Without --gap, it picks the same finding as next.
--no-copy: Prints instead of copying to the clipboard. It also prints when stdout is not a terminal.
next --json: type, title, detail and the command to run next, such as viberaven prompt --gap rls_policy_allows_all_write.

init

Writes VibeRaven rules for your coding agents, or a GitHub Actions workflow.

npx -y viberaven@1.7.8 init [path] [--agents all|<list>] [--dry-run] [--github]

--agents <list>: Comma-separated targets, such as claude,codex. The default is all.
--dry-run: Prints the files and the text, writes nothing.
--github: Writes two GitHub Actions workflows instead. Existing files are kept unless you add --force.

Details on Agent rules and CI.

audit

Groups the Vercel + Supabase evidence into eight checks, such as RLS policy proof, the pooler port and the service role boundary, each with its findings and fix lines. Reads local files only.

npx -y viberaven@1.7.8 audit --vercel-supabase [path] [--json]

Exit codes: 0 when every check passes, 1 when one needs work. --vercel-supabase is required.

rls-test

Experimental. Applies your Supabase migrations in PGlite, an in-memory Postgres, and tests who can read, change and delete rows against a permissions matrix you write by hand. It is an imitation, not your live database.

npx -y -p viberaven@1.7.8 -p @electric-sql/pglite@0.5.8 viberaven rls-test --json

viberaven.permissions.json: The matrix, in the project root: who should be allowed to do what, per table. It is never inferred from your policies.
--matrix <file>: A matrix at another path.
--migrations <dir>: Migrations in another folder.

PGlite is an optional package, so the command above adds it. Exit codes: 0 when every tested cell passes, 1 when one fails, 2 with only unknowns or no matrix.

public.posts  (RLS on, owner postgres)
  actor         action    expected  result   observed
  other_user    update    deny      Fail     1 row changed (body rewritten; owner row changed)
  anon          delete    deny      Pass     0 rows changed, the row is still there and unchanged

Result: 6 Pass, 3 Fail, 3 Unknown, 4 N/A · 9 of 12 tested cells observed (16 cells in the matrix)

npx -y viberaven@1.7.8 login --json
npx -y viberaven@1.7.8 account --json

login: Prints an approval link and waits up to 10 minutes while you approve in your browser. Exit 0 once signed in, 1 when the link expires or is denied.
--json: Prints the link as one JSON line on stderr and does not open a browser.
--no-browser: In text mode, prints the link without opening a browser.
account: Your plan, live allowance and upgrade link. Exit 1 when signed out.

Never pass a password or token as an argument. See Account and Pro.

connect

Links this folder to your app on viberaven.dev, so your coding agent can make changes there from the website. Copy the line from your app page; each line works once, for 10 minutes.

npx -y viberaven@1.7.8 connect --session <id> --token <code>

Keep the terminal open while you work; Ctrl+C disconnects. See Connect your app.

The Studio

With no command, viberaven opens the local Studio on your computer. No account is needed.

npx -y viberaven@1.7.8

In a coding agent's shell, such as Claude Code, Codex, Cursor or Gemini CLI, it runs check instead and says so on stderr. Use npx -y viberaven ui to open the Studio from there.

Strict mode

The older full scan, for CI that reads gate.status. It prints a summary box and writes .viberaven/gate-result.json.

npx -y viberaven@1.7.8 --strict
npx -y viberaven@1.7.8 --strict=warning

--strict exits 1 when gate.status is not_clear; --strict=warning also on warnings. Write it with =: --strict warning is read as a command. --strict has no effect after check, which already exits 1 on blockers.

Checked

Checked on November 3, 2026, against the published viberaven 1.7.8, with a real run on a small Next.js + Supabase + Stripe fixture repo.