Commands Reference

Complete reference for all vibe-init CLI commands and Agile Vibe Coding integration.

vibe init

Set up the vibe coding framework — generates CLAUDE.md, custom skills, guardrails, and project conventions. This is the first step in the vibe coding workflow.

vibe init                    # Interactive setup
vibe --dry-run init          # Preview files without writing

How it works

1. Detect project type — Greenfield (empty directory) or brownfield (existing code). Brownfield projects are scanned automatically.
2. Ask project name — Defaults to the directory name.
3. Ask stack preference — (Greenfield only) Next.js, Express, FastAPI, or Go.
4. Generate framework — Claude generates a comprehensive CLAUDE.md tailored to your stack + project context.

Generated files

File	Purpose
CLAUDE.md	Comprehensive AI coding instructions — conventions, architecture, security, testing
.claude/commands/test.md	Custom /test skill for Claude Code
.claude/commands/lint.md	Custom /lint skill
.claude/commands/build.md	Custom /build skill (lint + test + build)
.claude/commands/commit.md	Custom /commit skill (conventional commits)
.claude/commands/review.md	Custom /review skill (code quality review)
.claude/commands/add-feature.md	Custom /add-feature skill
.claude/settings.json	Permission allowlists and deny lists
docs/adr/000-template.md	Architecture Decision Record template
.gitignore	Stack-appropriate ignores (greenfield only)

Requirements

• Claude CLI — Required for CLAUDE.md generation
• ANTHROPIC_API_KEY — Optional (falls back to Claude CLI if not set)

vibe build

Build a project from your idea using the vibe framework. Takes you through enrichment, generates an ADR, then spawns Claude Code to build the project with full context.

vibe build                   # Interactive build flow
vibe --verbose build         # Show debug output

How it works

1. Ignition — Describe your idea in 1-5 sentences. Name your project.
2. Enrichment — Claude generates a structured brief: vision, personas, prioritized features (P0/P1/P2), tech stack, architecture, monetization, and go-to-market. You can accept, edit, or restart.
3. ADR — Architecture Decision Record auto-generated, documenting decisions, alternatives, trade-offs, and 12-Factor compliance.
4. Build — Claude Code is spawned interactively with your CLAUDE.md + enrichment brief + ADR as system context. It builds the entire project following your conventions.

Requirements

• Claude CLI — Required (spawns Claude Code for the build phase)
• CLAUDE.md — Must exist (run vibe init first)

vibe scan [dir]

Analyze any existing project using pure filesystem detection. No API keys, no external calls.

vibe scan                        # Scan current directory
vibe scan /path/to/project       # Scan a specific directory
vibe scan --generate-claude-md   # Also generate a CLAUDE.md file

Stack detection

Detectors run in specificity-first order (first match wins):

Stack	Detection method
Next.js	next.config.ts / next.config.js / next.config.mjs + package.json
Python / FastAPI	requirements.txt / pyproject.toml / setup.py
Go	go.mod
Node.js (generic)	package.json (fallback after framework-specific checks)

Practice detection

10 practice detectors run in parallel, checking for:

Practice	What it looks for
Docker	Dockerfile, docker-compose.yml
CI/CD	.github/workflows/, .gitlab-ci.yml, .circleci/
Testing	Test config files (Vitest, Jest, pytest, Go test) + test directories
Linting	ESLint, Biome, flake8, golangci-lint configs
Env Validation	Env config files (src/lib/env.ts), dotenv-safe/envalid in package.json
Logging	Top-level import statements for Pino, Winston, or structlog
Health Checks	Health route files by path convention (src/app/api/health/route.ts, src/routes/health.ts, etc.)
Git Hooks	.husky/, .pre-commit-config.yml, lefthook config
Security	.gitignore exists and excludes .env
Documentation	README.md, CLAUDE.md, docs/adr/

Flags

Flag	Description
--generate-claude-md	Generate a CLAUDE.md file with project context (uses API key if available, falls back to Claude CLI).

vibe add <feature> [args...]

Inject production features into any existing project. Idempotent and stack-aware — safe to run multiple times.

# Template-based features (instant, no API key needed)
vibe add docker          # Dockerfile + docker-compose.yml
vibe add ci              # GitHub Actions CI pipeline
vibe add testing         # Vitest config + sample test
vibe add logging         # Pino (Node) or structlog (Python)
vibe add validation      # Zod environment validation
vibe add health          # /api/health endpoint
vibe add hooks           # Husky + commitlint + lint-staged
vibe add auth            # Authentication setup guidance
vibe add db              # Prisma schema + client

# Claude-powered generators (require Claude CLI)
vibe add api users       # Generate REST API endpoint + test
vibe add component Card  # Generate React component + test
vibe add model Order     # Generate Prisma model + migration

How it works

1. Looks up the feature in the registry
2. Detects your project's stack (Next.js, Go, Python, Node.js)
3. Checks if the feature is already installed (skips with a warning unless --force)
4. Applies the feature: renders templates or calls Claude for generation
5. Prints created/modified files and next-step instructions

Flags

Flag	Description
--force	Overwrite existing files (skip the "already installed" check)
--verbose	Show debug output

See Features for a detailed breakdown of each feature module.

vibe doctor

Score your project against engineering best practices. Runs 17 weighted checks across 7 categories and returns a letter grade.

vibe doctor              # Run health checks
vibe --verbose doctor    # Show detailed check results

Scoring categories

Category	Weight	Checks
Testing	20 pts	Test framework config (8), test files exist (7), coverage config (5)
Security	20 pts	Env validation (8), auth setup (7), .gitignore with .env (4)
CI/CD	15 pts	Pipeline config file (10), additional CI checks (5)
Code Quality	15 pts	TypeScript strict (7), linter config (6), git hooks (6)
Containerization	10 pts	Dockerfile (6), docker-compose.yml (5)
Documentation	10 pts	README.md (5), CLAUDE.md (4)
Observability	10 pts	Health endpoint (7), structured logging (6), database setup (5)

Grade scale

Grade	Score range
A+	95-100
A	90-94
A-	85-89
B+	80-84
B	75-79
B-	70-74
C+	65-69
C	60-64
C-	55-59
D	40-54
F	0-39

Each failed check includes a suggestion pointing to the relevant vibe add command to fix it.

vibe anchor [feature]

Create or view feature context anchors — persistent decision documents that survive across AI chat sessions. Based on Martin Fowler's Context Anchoring pattern.

vibe anchor                     # List all anchored features
vibe anchor "user auth"          # Create context doc for a feature
vibe anchor "user auth"          # Revisit — shows status

What it creates

Each feature anchor is a markdown file at docs/context/<slug>.md with:

• Decisions table — Decision | Reason | Rejected Alternative (highest-value artifact)
• Constraints — Hard boundaries for this feature
• Open Questions — Checkbox list of unresolved items
• State — Milestone tracking (design, implementation, tests, review)
• Context for AI — What Claude needs to know when working on this feature

vibe audit

Alias for vibe doctor. Runs the governance compliance audit with 59 policies across 10 categories.

vibe audit                       # Run governance audit
vibe doctor                      # Same command

vibe run <task>

Spawn an interactive Claude Code session with your project's CLAUDE.md injected as system context. Claude understands your architecture, conventions, and patterns before writing any code.

vibe run "add pagination to the users API endpoint"
vibe run "refactor auth middleware for role-based access control"
vibe run "write integration tests for the checkout flow"
vibe run "add Redis caching to the product listing with 5-minute TTL"

Requirements

• Claude CLI — Must be installed and in your PATH
• CLAUDE.md — Must exist in your project root (generate one with vibe scan --generate-claude-md)

How it works

1. Reads your project's CLAUDE.md from the current directory
2. Builds a system prompt with the CLAUDE.md as project context
3. Spawns Claude Code in interactive mode with your task
4. You interact directly with Claude Code — it can edit files, run commands, and ask clarifications

vibe ask <question>

Ask Claude about your project in read-only advisory mode. No files are modified.

vibe ask "should I use Redis for sessions or stick with JWT?"
vibe ask "what are the security risks in the current auth setup?"
vibe ask "which endpoints might have N+1 query problems?"
vibe ask "what's the best approach to add multi-tenancy?"

Requirements

• Claude CLI — Must be installed and in your PATH
• CLAUDE.md — Must exist in your project root for context

Unlike vibe run, this command is non-interactive — it sends your question, prints Claude's response, and exits. No file modifications are possible.

Agile Vibe Coding (vibe avc)

New in v0.6.1 — vibe-init integrates with the Agile Vibe Coding framework for structured, traceable AI-assisted development. AVC is a companion CLI that provides agile ceremonies.

# Install AVC globally
npm install -g @agile-vibe-coding/avc

# Run AVC ceremonies in your project
cd your-project
vibe avc

Ceremonies

Ceremony	Purpose	Output
Sponsor Call	Define project vision, business goals, and priorities	Epics with business context and acceptance criteria
Sprint Planning	Break epics into implementable stories, estimate complexity	Sprint backlog with user stories, tasks, and traceability links

Workflow with vibe-init

# 1. Set up governance framework
vibe init

# 2. Plan with AVC ceremonies
vibe avc                          # Sponsor Call → Sprint Planning

# 3. Build with full traceability
vibe build                   # Claude builds with governance + agile context

# 4. Audit governance compliance
vibe audit                   # Includes traceability checks

Why AVC?

The Agile Vibe Coding Manifesto addresses the core problem with unstructured AI coding: zero traceability of decisions. Every epic, story, and task created by AVC links back to a requirement — so governance is auditable end-to-end.

Semantic Code Intelligence (vibe codegraph)

Pass-through wrapper around @colbymchenry/codegraph. Builds a local SQLite knowledge graph of your code so Claude Code's Explore agent can answer "how does X work?" with one MCP call instead of dozens of grep/read calls.

# Build the local index (auto-installs codegraph globally on first use)
vibe codegraph init -i

# Status / search / sync — all args pass through to the codegraph CLI
vibe codegraph status
vibe codegraph query UserService
vibe codegraph sync

vibe init wires up the matching CLAUDE.md guidance, a .claude/commands/codegraph.md skill, and pre-allows mcp__codegraph__* permissions so there are no permission prompts during exploration.

Multi-modal Knowledge Graph (vibe graphify)

New in v0.7.0 — pass-through wrapper around graphifyy (PyPI). Where CodeGraph indexes code symbols, Graphify builds a cross-modal graph spanning code, docs, papers, images, audio, and video. Outputs interactive HTML, queryable JSON, and a plain-language audit (graphify-out/GRAPH_REPORT.md).

# Build the graph (auto-installs graphifyy via uv → pipx → pip on first run)
vibe graphify .

# Wire up always-on hooks for your AI assistant
vibe graphify install

# Query the graph
vibe graphify query "show the auth flow"
vibe graphify path DigestAuth Response
vibe graphify explain UserService
vibe graphify stats

# Cross-repo
vibe graphify clone https://github.com/owner/repo
vibe graphify merge-graphs a/graph.json b/graph.json --out merged.json

Output

File	Purpose
graphify-out/graph.html	Interactive graph — open in any browser, click nodes, search, filter by community
graphify-out/GRAPH_REPORT.md	God nodes, surprising connections, suggested questions (one-page audit)
graphify-out/graph.json	Persistent graph — query weeks later without re-reading
graphify-out/cache/	SHA256 cache — re-runs only process changed files (gitignored)

Graphify vs CodeGraph

Use Graphify	Use CodeGraph
Cross-modal questions (docs ↔ code ↔ papers)	Pure code questions (callers, callees, impact)
"What is this project about?" / orientation	"What calls function X?"
Surprising connections, design rationale	Symbol lookup / blast-radius analysis
Mixed corpora (audio transcripts, images, PDFs)	Source-tree-only repos

Both can coexist in the same project. Every Graphify edge is tagged EXTRACTED (found directly in source), INFERRED (with a confidence score), or AMBIGUOUS (flagged for review) — no silent hallucination.

Global flags

These flags work with any command:

Flag	Description
--verbose, -v	Show detailed debug output and full error stack traces
--dry-run	Preview changes without writing files to disk
--version, -V	Print the installed version
--help, -h	Show help text (works on any command: vibe add --help)