Quick start
This guide will get you analyzing code with Vibrant in under 5 minutes.
Basic usage
Run Vibrant on your codebase
The simplest way to use Vibrant is to run it on your current directory:Or if you installed it globally:Vibrant automatically detects TypeScript and JavaScript files in common source directories like src/, lib/, app/, etc.
Review the results
Vibrant will analyze your code and display any issues found:🔮 Vibrant Analysis
───────────────────
✔ Analysis complete
✕ src/api.ts:24:5
└─ hardcoded-credentials
API key hardcoded in source code
24| const API_KEY = "sk-abc123...";
→ Use environment variables instead
⚠ src/utils.ts:85:1
└─ empty-catch-block
Empty catch block swallows errors
85| } catch (e) {}
→ Log or handle the error properly
✕ 1 error · ⚠ 1 warning · 48 files · 200ms
- ✕ (red) indicates errors - critical issues that should be fixed
- ⚠ (yellow) indicates warnings - issues that should be reviewed
Fix issues automatically (optional)
Some issues can be automatically fixed:This will fix issues like:
- Removing
console.log statements
- Adding error handling to empty catch blocks
- Other auto-fixable patterns
Analyze specific files or directories
You can target specific paths:
Ignore files
Exclude certain files or directories from analysis:
vibrant . --ignore "dist,coverage,*.test.ts"
vibrant.config.js:
module.exports = {
ignore: ['node_modules', '.git', 'dist', '*.test.ts', 'coverage']
};
AI-powered analysis
AI analysis requires an API key. See the Installation guide for setup instructions. Set up your API key
Create a .env file in your project:OPENROUTER_API_KEY="sk-or-v1-..."
OpenRouter offers free models and is recommended for getting started. See Installation for other providers. Run AI analysis
You’ll see enhanced analysis with:
- Overall code health assessment
- Key findings and patterns
- Actionable recommendations
Review AI insights
🔮 Vibrant Analysis
───────────────────
✔ Analysis complete
🔍 Issues Found
[... issues ...]
📊 Diagnosis
The codebase shows signs of AI-generated code with
multiple hardcoded credentials and incomplete error
handling patterns.
⚡ Key Findings
• 3 hardcoded API keys need to be moved to environment variables
• 5 empty catch blocks silently swallow errors
• 12 console.log statements should be removed
💡 Recommendations
→ Move all credentials to environment variables using dotenv
→ Add proper error logging in catch blocks
→ Remove debug console.log statements before production
✕ 8 errors · ⚠ 12 warnings · 48 files · 10.2s
Choose a specific AI provider
Use a different AI provider:
vibrant . --ai --provider openrouter
Pretty (default)
Compact
JSON
Plan
Human-readable output with colors:Best for: Interactive terminal usage Single-line output for each issue:vibrant . --format compact
src/api.ts:24:5 error hardcoded-credentials API key in source
src/utils.ts:85:1 warning empty-catch-block Swallows errors
Machine-readable JSON output:vibrant . --format json > report.json
Detailed markdown report:Creates vibrant-report.md with:
- Complete issue list with code snippets
- Suggested fixes for each issue
- Priority ordering (errors first)
Best for: AI assistants to auto-fix issues, documentation Common commands
List all detection rules
See all available rules Vibrant can detect:
Output:
📋 Available Detection Rules
Security
──────────────────────────────────────────────────────
hardcoded-credentials Hardcoded API keys, passwords
no-sql-injection SQL injection vulnerabilities
no-unsafe-inner-html XSS via innerHTML
Bugs
──────────────────────────────────────────────────────
empty-catch-block Empty catch blocks
unimplemented-error Unimplemented code
empty-function-body Empty functions
[...]
View help
Get help on available commands and options:
Check version
Display the installed version:
Ignoring false positives
Sometimes you need to ignore specific lines:
// vibrant ignore
const debug = true;
CI/CD integration
Integrate Vibrant into your continuous integration pipeline:
name: Code Quality
on: [push, pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Run Vibrant
run: npx vibrant-cli . --format compact
Vibrant exits with code 1 if errors are found, and 0 if no issues or only warnings. This integrates naturally with CI/CD systems.
Next steps
CLI reference
Complete reference for all commands and options
Detection rules
Learn about all the patterns Vibrant can detect
Configuration
Customize Vibrant for your project
AI providers
Deep dive into AI-powered analysis