@viberaven/cli

@viberaven/cli

VibeRaven is the Agent Context + Production Gate for AI-built apps. It gives Claude Code, Codex, Cursor, and other coding agents a production-readiness loop before Vercel/Supabase deployment.

Humans

npx -y viberaven

No subcommand is needed in a real terminal. It opens the interactive menu for sign-in, scan, report, provider guides, dashboards, prompts, and sign-out.

Coding Agents

Agents should run:

npx -y viberaven --agent-mode

If running from the viberaven monorepo root, run:

node packages/cli/dist/cli.js --agent-mode

Then read artifacts in this order:

• .viberaven/agent-tasklist.md
• .viberaven/gate-result.json
• .viberaven/context-map.json
• .viberaven/agent-summary.md
• .viberaven/launch-playbook.md

Fix one repo-code gap, then run:

npx -y viberaven --verify
npx -y viberaven --strict

For focused work:

npx -y viberaven next --json
npx -y viberaven prompt --gap <id>
npx -y viberaven audit --vercel-supabase

Chat-native production actions

Agent mode writes a compact action surface for Codex, Claude Code, Cursor, and other agents:

npx -y viberaven --agent-mode
npx -y viberaven actions
npx -y viberaven verify --action VR-A1

VibeRaven writes .viberaven/actions.json as the V1 source of truth and renderer contract for the current action surface. The manifest is generated by --agent-mode; .viberaven/action-registry.json preserves stable action handles across runs.

Chat output is intentionally limited to focused actions, provider targets, copy payloads, verification commands, repo-relative file targets, and resume prompts. It does not print secrets, raw env values, or generic dashboard link dumps.

Provider dashboard checks are not cleared by repo-code edits. Billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must be completed or verified in the provider dashboard or through read-only provider evidence.

Preview the action surface without login, scan, or API spend:

npx -y viberaven preview --agent-mode

The preview uses sample renderer data to show the intended chat-native shape. It is not a production verdict for the current repository.

Agent infrastructure direction

VibeRaven's action model is designed for normal Codex, Claude Code, Cursor, and MCP workflows today, and for richer agent hosts later.

Managed-agent systems need durable sessions, observable event history, credential boundaries, bounded execution, and resumable action state. VibeRaven keeps those concerns in the manifest contract:

• .viberaven/actions.json is the current action surface.
• .viberaven/action-registry.json preserves stable IDs and lifecycle history.
• Future session events can add an append-only timeline without changing the current action model.
• Provider credentials and raw env values must stay out of chat output, manifests, MCP resources, and UI renderers.
• Future local/hosted consoles should execute only narrow VibeRaven commands, not arbitrary shell text.

Production Copilot Loop

VibeRaven runs a batch-disciplined loop until the production gate clears. Do not stop at "scan complete."

• Scan — Run --agent-mode. Read .viberaven/agent-tasklist.md and parse VIBERAVEN_NEXT_ACTION from stdout for batchSize, batchApplied, scanNow, and stalled.
• Batch heals — For each repo-code task where requiresUserAction: false, apply up to batchSize heals per batch (free=3, pro=10) via viberaven_heal_apply { gap: "<gapId>", yes: true } or --heal --apply --gap <id> --yes. When scanNow: true, verify before applying more heals.
• Verify and clear — Run --verify once per batch (not after every heal). Repeat until gate.status === 'clear' in .viberaven/gate-result.json. For provider gaps, read VIBERAVEN_PROVIDER_ACTION, complete the dashboard step, then verify.

If stalled: true, stop calling verify and address provider-action gaps or report to the user. Run --strict before deploy or CI pass.

Machine Output

npx -y viberaven --agent-mode --json
npx -y viberaven --agent-mode --jsonl
npx -y viberaven --strict --json

Machine artifact contract:

docs/contracts/artifacts.md
https://viberaven.dev/schemas/gate-result.schema.json
https://viberaven.dev/schemas/context-map.schema.json
https://viberaven.dev/schemas/gap.schema.json
https://viberaven.dev/schemas/heal-result.schema.json

Development

npm run cli:build
npm run cli:test
node packages/cli/dist/cli.js scan

License

The public npm CLI package is MIT licensed. Private monorepo code and extension packaging may have separate product terms.