CLI Commands
Complete reference for all Oculum CLI commands. Install with npm install -g @oculum/cli.
Command Overview
| Command | Description |
|---|---|
scan | Scan files for security vulnerabilities |
watch | Continuously scan on file changes |
login | Authenticate with Oculum |
logout | Remove stored credentials |
status | Check authentication status |
usage | View credits and usage |
ignore | Manage finding suppressions |
baseline | Manage security baselines |
history | View scan history |
ui | Open interactive terminal UI |
upgrade | View upgrade options |
scan
Scan files for security vulnerabilities.
oculum scan [path] [options]
Options
| Flag | Description | Default |
|---|---|---|
-d, --depth <depth> | Scan depth: local, verified, deep | local |
-f, --format <format> | Output: terminal, json, sarif, markdown | terminal |
--fail-on <severity> | Exit 1 on severity: critical, high, medium, low, none | none |
--fail-on-categories <cats> | Exit 1 on specific categories (comma-separated, supports ai-*) | - |
-o, --output <file> | Write output to file | - |
-i, --ignore <pattern> | Ignore pattern (can repeat) | - |
--incremental | Only scan changed files | false |
--diff <ref> | Compare against branch/commit | - |
--new | Show only new findings vs baseline | false |
--show-suppressed | Include suppressed findings | false |
-p, --profile <name> | Use named profile from config | - |
-q, --quiet | Minimal output | false |
-v, --verbose | Debug output | false |
-c, --compact | Compact output (severity + title + location) | false |
--no-color | Disable colored output | false |
IDE Integration Flags
| Flag | Description |
|---|---|
--ai-context | Generate .oculum/ai-context.md |
--cursor | Generate Cursor rules |
--windsurf | Generate Windsurf rules |
--claude-code | Update CLAUDE.md security section |
--ide-rules | Auto-detect and update all IDE configs |
--clear | Clear IDE rule files |
Examples
# Basic scan
oculum scan
# Scan specific directory with verified depth
oculum scan src/ --depth verified
# Fail CI on high severity
oculum scan --fail-on high --quiet
# Output JSON to file
oculum scan --format json --output results.json
# Incremental scan against main
oculum scan --diff main --fail-on critical
# Use CI profile
oculum scan -p ci
watch
Continuously scan on file changes.
oculum watch [path] [options]
Options
| Flag | Description | Default |
|---|---|---|
-d, --depth <depth> | Scan depth | local |
--debounce <ms> | Wait after last change | 500 |
--cooldown <seconds> | Minimum time between scans | 10 |
--clear | Clear console before each scan | false |
-q, --quiet | Minimal output | false |
Keyboard Controls
r— Manual rescanc— Clear consolep— Pause/resumeq— Quit
Example
oculum watch --clear --depth verified
login
Authenticate with Oculum.
oculum login [options]
Options
| Flag | Description |
|---|---|
-k, --api-key <key> | Authenticate with API key (skips browser) |
Examples
# Browser OAuth
oculum login
# API key (for CI/headless)
oculum login --api-key ocu_abc123...
logout
Remove stored credentials.
oculum logout
status
Check authentication status.
oculum status
Output
Logged in as: user@example.com
Plan: Pro
Scan depths: local, verified, deep
Credits: 45 / 250 (18%)
Reset date: February 1, 2026
usage
View credits and usage.
oculum usage [options]
Options
| Flag | Description |
|---|---|
--json | Output as JSON |
ignore
Manage finding suppressions.
oculum ignore [hash] [options]
Modes
# Add suppression
oculum ignore abc123def4567890 --reason "False positive"
# With expiration
oculum ignore abc123def4567890 --reason "Approved" --expires 2026-06-01
# List suppressions
oculum ignore --list
# Remove suppression
oculum ignore --remove abc123def4567890
Options
| Flag | Description |
|---|---|
--reason <text> | Reason for suppression (required for add) |
--expires <date> | Expiration date (YYYY-MM-DD) |
--list | List all suppressions |
--remove <hash> | Remove a suppression |
baseline
Manage security baselines.
oculum baseline <subcommand> [path] [options]
Subcommands
# Create baseline
oculum baseline create
oculum baseline create --depth verified
# Show baseline info
oculum baseline show
# Clear baseline
oculum baseline clear
Options
| Flag | Description |
|---|---|
-d, --depth <depth> | Scan depth for create |
-q, --quiet | Minimal output |
history
View scan history.
oculum history [subcommand] [id]
Subcommands
# List recent scans
oculum history
# Show scan details
oculum history show abc123
# Delete scan
oculum history delete abc123
# Clear all history
oculum history clear
ui
Open interactive terminal UI.
oculum ui
Features:
- Browse findings interactively
- Filter by severity
- Navigate to code locations
- Suppress findings
upgrade
View upgrade options.
oculum upgrade
Shows current plan limitations and upgrade information.
Global Options
These work with all commands:
| Flag | Description |
|---|---|
-h, --help | Show help |
-V, --version | Show version |
Environment Variables
| Variable | Description |
|---|---|
OCULUM_API_KEY | API key for authentication |
export OCULUM_API_KEY=ocu_abc123...
oculum scan --depth verified
Related
- Config Files — Configuration reference
- Scan Depths — Understanding scan modes
- Exit Codes — CI/CD integration