Configuration

Customize Oculum's behavior with configuration files, profiles, and ignore patterns.

Config Files

Oculum looks for configuration in this order (first found wins):

oculum.config.json
.oculumrc.json
.oculumrc

Place the config file in your project root.

Config Options

{
  "depth": "cheap",
  "failOn": "none",
  "format": "terminal",
  "output": null,
  "quiet": false,
  "verbose": false,
  "ignore": [],
  "include": [],
  "profiles": {},
  "watch": {}
}

Option Reference

Option	Type	Default	Description
`depth`	string	`"cheap"`	Default scan depth: `cheap`, `validated`, `deep`
`failOn`	string	`"none"`	Exit 1 on severity: `critical`, `high`, `medium`, `low`, `none`
`format`	string	`"terminal"`	Output format: `terminal`, `json`, `sarif`, `markdown`
`output`	string	`null`	Write output to this file path
`quiet`	boolean	`false`	Minimal output
`verbose`	boolean	`false`	Debug output
`ignore`	string[]	`[]`	Glob patterns to ignore
`include`	string[]	`[]`	Only scan files matching these patterns
`profiles`	object	`{}`	Named configuration profiles
`watch`	object	`{}`	Watch mode settings

Profiles

Profiles let you save different configurations for different use cases.

Defining Profiles

{
  "depth": "cheap",
  "profiles": {
    "ci": {
      "depth": "validated",
      "format": "sarif",
      "output": "results.sarif",
      "quiet": true,
      "failOn": "high"
    },
    "audit": {
      "depth": "deep",
      "format": "json",
      "output": "audit-report.json"
    },
    "quick": {
      "depth": "cheap",
      "ignore": ["**/*.test.ts", "**/*.spec.ts"]
    }
  }
}

Using Profiles

# Use the CI profile
oculum scan -p ci

# Use the audit profile
oculum scan -p audit

# Profile + CLI flag (CLI wins)
oculum scan -p ci --verbose

Priority Order

When options conflict, this order determines the winner:

CLI flags (highest priority)
Profile settings
Project config file
Built-in defaults (lowest priority)

Watch Options

Configure watch mode defaults:

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

Option	Type	Default	Description
`debounce`	number	`500`	Milliseconds to wait after last change
`cooldown`	number	`10`	Minimum seconds between scans
`clear`	boolean	`false`	Clear console before each scan

.oculumignore

Create a .oculumignore file for gitignore-style patterns. One pattern per line.

Example

# Comments start with #

# Ignore test files
**/*.test.ts
**/*.spec.ts
__tests__/

# Ignore fixtures and mocks
fixtures/
**/*.mock.ts
**/*.fixture.ts

# Ignore legacy code
legacy/
deprecated/

# Ignore minified files
*.min.js
*.bundle.js

# Ignore generated code
generated/
.next/
dist/

Pattern Syntax

Pattern	Matches
`*.test.ts`	Files ending in `.test.ts` in current directory
`*/.test.ts`	Files ending in `.test.ts` anywhere
`tests/`	Directory named `tests` and all contents
`src/legacy/*`	Files directly in `src/legacy/`
`src/legacy/**`	All files under `src/legacy/` recursively

Default Ignore Patterns

These patterns are always ignored (you don't need to add them):

Directories

node_modules/
dist/, build/, out/
.git/, .svn/
coverage/
.next/, .nuxt/, .turbo/
vendor/, venv/, .venv/

Files

package-lock.json, yarn.lock, pnpm-lock.yaml
*.min.js, *.bundle.js
Binary files (images, fonts, etc.)

Include Patterns

Use include to scan only specific files/directories:

{
  "include": [
    "src/**",
    "lib/**"
  ]
}

When include is set, only files matching these patterns are scanned.

Combining Include and Ignore

{
  "include": ["src/**"],
  "ignore": ["src/**/*.test.ts"]
}

This scans everything in src/ except test files.

Environment Variables

Variable	Description
`OCULUM_API_KEY`	API key for authentication (alternative to `oculum login`)

CI/CD Example

# GitHub Actions
env:
  OCULUM_API_KEY: ${{ secrets.OCULUM_API_KEY }}

steps:
  - run: oculum scan --depth validated

Example Configurations

Basic Project

{
  "ignore": [
    "**/*.test.ts",
    "**/*.spec.ts"
  ]
}

Monorepo

{
  "include": [
    "packages/api/src/**",
    "packages/web/src/**"
  ],
  "ignore": [
    "**/__tests__/**",
    "**/fixtures/**"
  ],
  "profiles": {
    "api": {
      "include": ["packages/api/src/**"]
    },
    "web": {
      "include": ["packages/web/src/**"]
    }
  }
}

Full CI Setup

{
  "depth": "cheap",
  "profiles": {
    "ci": {
      "depth": "validated",
      "format": "sarif",
      "output": "results.sarif",
      "failOn": "high",
      "quiet": true
    },
    "pr": {
      "depth": "cheap",
      "failOn": "critical"
    }
  },
  "ignore": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/__mocks__/**"
  ]
}

Use with:

# On PRs - quick feedback
oculum scan -p pr --incremental

# On main - thorough scan
oculum scan -p ci

scan - Scan command options
watch - Watch mode
GitHub Action - CI/CD integration