Quickstart

Get up and running with Oculum in 5 minutes. This guide walks you through installing the CLI, running your first scan, and understanding the results.

Prerequisites

• Node.js 18+ (LTS recommended)
• npm, pnpm, or bun (for installation)
• GitHub account (optional, for authenticated features)

Installation

Install the Oculum CLI globally:

npm install -g @oculum/cli

Or use npx to run without installing:

npx @oculum/cli scan

Verify installation:

oculum --version

Tip: You can also use oc as a shorthand for oculum.

Your First Scan

Navigate to your project and run a scan:

cd your-project
oculum scan

That's it! Oculum will:

1. Detect your project type
2. Scan all supported files
3. Display results in your terminal

Supported File Types

Oculum scans these file types:

Understanding Results

Results are displayed with severity indicators:

Example Output

┌────────────────────────────────────────────────────────────────┐
│  Oculum Security Scan                                          │
│  Repository: my-ai-app                                         │
│  Files scanned: 47                                             │
└────────────────────────────────────────────────────────────────┘

Found 3 issues:

🔴 CRITICAL: Hardcoded API Key
   src/lib/openai.ts:12
   API key exposed in source code
   → Use environment variables instead

🟠 HIGH: Unvalidated User Input to LLM
   src/api/chat.ts:45
   User input passed directly to prompt without sanitization
   → Sanitize or validate user input before use

🟡 MEDIUM: Missing Rate Limiting
   src/api/chat.ts:1
   No rate limiting on AI endpoint
   → Consider adding rate limiting

Scan completed in 1.2s

Scan Depths

Oculum offers three scan depths:

validated and deep scans require authentication.

→ See Scan Depths for detailed comparison.

Authentication (Optional)

Authentication unlocks:

• AI-validated scans (fewer false positives)
• Deep semantic analysis
• Dashboard sync
• API access

Option A: Browser OAuth

oculum login

This opens your browser for GitHub authentication.

Option B: API Key

oculum login --api-key YOUR_KEY

Get your API key from the Dashboard Settings.

Check Status

oculum status

Common Options

# Scan specific directory
oculum scan src/

# Use validated scan depth
oculum scan --depth validated

# Output as JSON
oculum scan --format json

# Save to file
oculum scan --output report.json --format json

# Fail CI if critical/high issues found
oculum scan --fail-on high

# Only scan changed files
oculum scan --incremental

Troubleshooting

"No issues found" but expected some

• Check file types: Oculum only scans supported extensions
• Try validated scan: Pattern matching may miss context-dependent issues
• Check ignore patterns: See if files are excluded in .oculumignore

# Run with verbose output
oculum scan --verbose

Authentication errors

# Re-authenticate
oculum login

# Check current status
oculum status

Network/proxy issues

If behind a firewall or proxy:

# Set proxy environment variables
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

Slow scans

• Use cheap depth for quick feedback
• Add ignore patterns for large directories
• Use --incremental to scan only changed files

File permission errors

Ensure you have read access to all files in the project directory.

Next Steps

Now that you've run your first scan:

• Scan Depths — Understand cheap, validated, and deep scans
• CLI Reference — All commands and options
• GitHub Action — Set up CI/CD integration
• API Reference — Programmatic scanning
• Credits & Usage — Understand quotas and plans