CLI Reference

The Oculum CLI provides powerful security scanning directly from your terminal. Install it globally and start scanning in seconds.

Installation

npm install -g @oculum/cli

Binary names: oculum or oc (shorthand)

Verify installation:

oculum --version

Commands

Command	Description
`scan`	Scan for security vulnerabilities
`watch`	Watch files and scan on changes
`login`	Authenticate with Oculum
`status`	Check authentication status
`usage`	View credits and quota
`history`	Manage scan history
`ui`	Launch interactive terminal interface
`help`	Get help on topics
`upgrade`	Upgrade your plan

Quick Start

Basic Scan

# Scan current directory
oculum scan

# Scan specific directory
oculum scan src/

Validated Scan

Get AI-validated results with ~70% fewer false positives:

oculum scan --depth validated

Requires authentication.

Watch Mode

Continuous scanning during development:

oculum watch

Interactive Mode

Launch the TUI for guided scanning:

oculum ui
# or just
oculum

Scan Depths

Depth	Description	Best For
`cheap`	Fast pattern matching	Quick PR checks, local dev
`validated`	AI validates findings	Interactive development
`deep`	Full semantic analysis	Security audits

See Scan Depths for full details.

Output Formats

# Terminal (default) - human-readable
oculum scan

# JSON - for integrations
oculum scan -f json -o results.json

# SARIF - for GitHub Security
oculum scan -f sarif -o results.sarif

# Markdown - for reports
oculum scan -f markdown -o report.md

CI/CD Integration

# Fail on high severity issues
oculum scan --fail-on high

# Quiet mode + SARIF output
oculum scan -f sarif -o results.sarif --fail-on high --quiet

# Only scan changed files
oculum scan --incremental

See GitHub Action for full CI setup.

Configuration

Create oculum.config.json in your project root:

{
  "depth": "cheap",
  "ignore": ["**/*.test.ts"],
  "profiles": {
    "ci": {
      "depth": "validated",
      "failOn": "high"
    }
  }
}

Use profiles:

oculum scan -p ci

See Configuration for all options.

Exit Codes

Code	Meaning
`0`	Success (no findings above threshold)
`1`	Findings found at or above `--fail-on` severity
`130`	User cancelled (Ctrl+C)

Detailed Documentation

scan - Full scan command reference with all options and examples
watch - Watch mode for continuous scanning
login - Authentication, account commands, and history management
ui - Interactive terminal interface
Configuration - Config files, profiles, and ignore patterns

Quickstart - Get started with Oculum
Scan Depths - Understand scan modes
Credits & Usage - Plans and quotas
GitHub Action - CI/CD integration