login & Account
Authentication commands for managing your Oculum account from the CLI.
login
Authenticate with Oculum to unlock validated/deep scans and dashboard sync.
oculum login [options]
Options
| Flag | Description |
|---|---|
-k, --api-key <key> | Authenticate directly with an API key (skips browser) |
Browser OAuth
The default method opens your browser for GitHub authentication:
oculum login
- Opens your default browser
- Sign in with GitHub
- Authorize Oculum
- CLI automatically receives credentials
API Key Authentication
For headless environments or CI/CD, use an API key:
oculum login --api-key ocu_abc123...
Get your API key from Dashboard Settings.
Environment Variable
You can also set your API key as an environment variable:
export OCULUM_API_KEY=ocu_abc123...
oculum scan --depth validated # Works without explicit login
status
Check your current authentication status.
oculum status
Example Output
Logged in as: user@example.com
Plan: Pro
Scan depths: cheap, validated, deep
Credits: 45 / 250 (18%)
Reset date: February 1, 2026
If not logged in:
Not authenticated.
Run 'oculum login' to authenticate.
usage
View your current credits and recent scan activity.
oculum usage [options]
Options
| Flag | Description |
|---|---|
--json | Output as JSON (for scripting) |
Example Output
Plan: Pro
Credits: 45 / 250 (18%)
Recent Scans:
my-project validated 2 min ago
api-service cheap 1 hour ago
web-app deep 3 hours ago
Reset Date: February 1, 2026
JSON Output
oculum usage --json
{
"plan": "pro",
"creditsUsed": 45,
"creditsTotal": 250,
"creditsPercent": 18,
"resetDate": "2026-02-01T00:00:00Z",
"recentScans": [
{
"project": "my-project",
"depth": "validated",
"timestamp": "2026-01-20T10:30:00Z"
}
]
}
history
View and manage your scan history.
oculum history [subcommand] [id]
Subcommands
| Command | Description |
|---|---|
| (none) | List recent scans (up to 25) |
show <id> | View detailed scan results |
delete <id> | Remove a scan from history |
clear | Clear all scan history |
List Scans
oculum history
Recent Scans:
ID Project Depth Findings Date
abc123 my-app validated 3 2 hours ago
def456 api-service cheap 0 1 day ago
ghi789 web-client deep 7 3 days ago
View Scan Details
oculum history show abc123
Shows full findings from a previous scan.
Export Scan
oculum history show abc123 -f json -o scan.json
Delete Scan
oculum history delete abc123
Clear All History
oculum history clear
Note: Partial ID matching is supported. abc will match abc123.
upgrade
Open information about upgrading your plan.
oculum upgrade
Shows current plan limitations and opens upgrade options.
logout
Remove stored credentials from your machine.
oculum logout
Credentials are stored in ~/.oculum/credentials.json.
Why Authenticate?
Authentication unlocks several features:
| Feature | Free (No Auth) | Authenticated |
|---|---|---|
| Cheap scans | Yes | Yes |
| Validated scans | No | Yes (Starter+) |
| Deep scans | No | Yes (Pro+) |
| Dashboard sync | No | Yes |
| Scan history | Local only | Cloud + local |
See Credits & Usage for plan details.
Related
- scan - Running scans
- Credits & Usage - Plans and quotas
- Dashboard Settings - Manage API keys