Getting Started

Prerequisites: Node.js 18+ and npm installed. (Check with node -v and npm -v)
Optional: Git for version control, Docker for self-hosting.

Install Whisper globally with npm:

npm install -g whisper-ai

Or run it instantly with npx:

npx whisper-ai scan .

After install, try:

whisper scan .

Troubleshooting

If whisper is not found, try restarting your terminal or ensure npm global bin is in your $PATH.
For permission errors, use sudo npm install -g whisper-ai (Linux/Mac).
On Windows, run your terminal as Administrator.

CLI Commands

whisper scan [path]

Scan your codebase for vulnerabilities. Supports AI-powered analysis and multiple output formats.

whisper scan . whisper scan ./src --ai --format html --output report.html

--ai: Enable AI-powered analysis (default: true)
--format: Output format (markdown, html, json, csv)
--output: Output file path
--fix: Attempt to auto-fix issues (see whisper fix)
--ignore: Ignore patterns (comma-separated)
--include: Include patterns (comma-separated)
--max-files: Maximum files to scan
--model: AI model to use (gemini, openai, claude)
--severity: Minimum severity level (low, medium, high, critical)

See How It Works for more details.

whisper fix [path]

Get AI-powered fix suggestions for issues found in your last scan. Interactive mode supported.

whisper fix . --interactive --severity high

--interactive: Interactive mode for applying fixes
--severity: Minimum severity level to fix
--model: AI model to use

whisper explain <file>

Explain code or security risks in a file or function.

whisper explain src/app.js --line 42 whisper explain src/utils.js --function loginUser

--line: Specific line number to explain
--function: Function name to explain
--security: Focus on security aspects
--model: AI model to use

whisper team [subcommand]

Team and organization management. (Requires team plan)

whisper team sync --project my-app --org my-org whisper team invite user@email.com --role admin

sync: Sync with team dashboard
invite: Invite team member
--role: Team role (admin, member, viewer)

whisper config [get|set|list]

Manage CLI configuration (API key, model, etc).

whisper config get apiKey whisper config set apiKey my-key whisper config list

whisper analytics usage

Show usage statistics (Pro/Team plans).

whisper analytics usage --period week

whisper chat

Interactive AI chat mode for code security questions.

whisper chat --model gemini --context ./src

whisper guard

Git pre-commit security guard. Blocks risky commits based on scan results.

whisper guard --install whisper guard --uninstall --severity high

--install: Install pre-commit hook
--uninstall: Uninstall pre-commit hook
--severity: Block commits with issues above this level

whisper plugin [install|list|remove]

Plugin management. Extend Whisper with custom plugins.

whisper plugin install my-plugin whisper plugin list whisper plugin remove my-plugin

whisper history

View chat and scan history.

whisper history --chat whisper history --scans whisper history --clear

whisper doctor

Diagnose and fix common issues.

whisper doctor

Self-Hosting

Whisper is open source and can be self-hosted for full control and privacy.

Clone the repo:

git clone https://github.com/your-org/whisper.git cd whisper

Install dependencies:
```
pnpm install
```

Set up environment variables:

cp .env.example .env # Edit .env with your DB, API keys, etc.

Set up the database:
```
pnpm run db:migrate
```
Run locally:
```
pnpm dev
```
(Optional) Run with Docker:
```
docker compose up --build
```

See GitHub for advanced configuration, environment variables, and deployment guides.

Advanced Guides

CI/CD Integration

Automate security scans in your pipelines.

GitHub Actions Example:

name: Whisper Security Scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: 18 - run: npm install -g whisper-ai - run: whisper scan . --format html --output report.html

GitLab CI Example:

whisper_scan: image: node:18 script: - npm install -g whisper-ai - whisper scan . --format markdown --output scan.md only: - merge_requests - main

Custom AI Model Configuration

You can specify which AI model to use for analysis and fixes:

whisper scan . --model gemini whisper fix . --model openai

Supported models: gemini, openai, claude (see FAQ for more).

Writing Plugins

Extend Whisper with custom plugins for new rules, integrations, or workflows.

Create a new JS file in lib/plugins/.
Export a function that receives the scan context and findings.
Register your plugin in lib/plugins/index.js.

// my-plugin.js
module.exports = function(context, findings) {
  // Custom logic here
  return findings;
};

See plugin examples on GitHub.

Advanced CLI Usage

Chain commands, use in scripts, or automate with shell tools:

# Scan and auto-fix in one line
whisper scan . && whisper fix .

# Save output and email report
whisper scan . --format html --output report.html && mail -s "Scan Report" you@email.com < report.html

Security Best Practices

Keep Whisper and dependencies up to date.
Review AI-generated fixes before applying in production.
Use whisper guard to block risky commits.
Integrate scans into CI/CD for every PR.
Limit API key exposure and rotate keys regularly.

Troubleshooting Advanced Issues

For memory or timeout errors, increase Node.js memory: NODE_OPTIONS=--max-old-space-size=4096 whisper scan .
Check logs in ~/.whisper/logs for debugging.
For plugin errors, disable plugins with --no-plugins.
Open an issue on GitHub with logs and steps to reproduce.

How It Works

Install: Whisper is a Node.js CLI. Install globally with npm or use npx for one-off runs.
Scan: Run whisper scan . in your project directory. Whisper analyzes your code for vulnerabilities using advanced AI models.
Review: Get a clear, actionable report in your terminal or dashboard.
Fix: Use whisper fix . to get AI-powered suggestions or auto-fixes for issues found.
Collaborate: Share results, manage projects, and sync with your team using the dashboard or CLI team commands.

FAQ

Is Whisper open source?

Yes! Whisper is open source and available on GitHub.

Do I need Node.js installed?

Yes, Whisper is a Node.js CLI. You need Node.js 18+ installed to use it.

Can I use Whisper in CI/CD?

Absolutely! Whisper is designed for automation and can be integrated into any CI/CD pipeline.

How do I get support?

Open an issue on GitHub or reach out via email.

How do I self-host Whisper?

See the Self-Hosting section above for step-by-step instructions.

Can I contribute?

Yes! Contributions are welcome. Fork the repo, open a PR, or suggest features via GitHub Issues.

Does Whisper support plugins?

Yes, you can install, list, and remove plugins using the whisper plugin command.

Where can I find more examples?

Check the examples directory on GitHub for more usage patterns.

Whisper Docs