watch

Monitor files and automatically scan for vulnerabilities when changes are detected. Ideal for continuous security feedback during development.

oculum watch [path] [options]

Path: Directory to watch. Defaults to current directory (.).

Options

Flag	Description	Default
`-d, --depth <depth>`	Scan depth: `cheap`, `validated`, `deep`	`cheap`
`--debounce <ms>`	Wait time after last change before scanning (milliseconds)	`500`
`--cooldown <seconds>`	Minimum time between scans (prevents rapid re-scans)	`10`
`--clear`	Clear console before each scan for cleaner output	`false`
`-q, --quiet`	Minimal output	`false`

Keyboard Controls

While watch mode is running, you can use these keyboard shortcuts:

Key	Action
`r`	Manually trigger a full rescan of all files
`c`	Clear the console
`p`	Pause/resume file watching
`q`	Quit watch mode

How It Works

Initial scan - When you start watch mode, Oculum performs a full scan
File monitoring - Watches for changes to scannable files (JS, TS, Python, etc.)
Debouncing - Waits for you to stop typing before scanning
Incremental scan - Only rescans the changed files, not the entire project
Cooldown - Prevents excessive scanning during rapid edits

Examples

Basic Usage

# Watch current directory
oculum watch

# Watch specific directory
oculum watch src/

# Watch with validated scans (more accurate)
oculum watch --depth validated

Clear Console Mode

Keep your terminal clean with automatic clearing:

oculum watch --clear

This clears the screen before each scan result, showing only the latest findings.

Heavy Projects

For large projects with many files, increase the cooldown:

# 30 seconds between scans
oculum watch --cooldown 30

# Longer debounce for slow file systems
oculum watch --debounce 1000

Development Workflow

Combine with your development server:

# Terminal 1: Start your dev server
npm run dev

# Terminal 2: Watch for security issues
oculum watch --clear --depth validated

Configuration

You can set default watch options in your config file:

{
  "watch": {
    "debounce": 500,
    "cooldown": 10,
    "clear": true
  }
}

See Configuration for more details.

Watched File Types

Watch mode monitors the same file types as regular scans:

JavaScript/TypeScript: .js, .jsx, .ts, .tsx
Python: .py
Go: .go
Config files: .json, .yaml, .yml, .toml
Special files: Dockerfile, .env*, package.json

Changes to non-scannable files (like .css or images) are ignored.

Tips

When to Use Watch Mode

During active development when writing new code
When refactoring security-sensitive areas
Learning about security patterns in your codebase

When to Use Regular Scans Instead

In CI/CD pipelines (use oculum scan)
For one-time security audits
When you need specific output formats (JSON, SARIF)

Performance

cheap depth is fast enough for real-time feedback
validated depth may have noticeable delay but catches more issues
Avoid deep depth in watch mode (too slow for real-time use)

scan - One-time scanning
Configuration - Config files and defaults
ui - Interactive terminal interface