Cli Commands
Complete reference for BlockSecOps CLI commands. --- These options work with all commands: | Option | Description | |--------|-------------| | --help | Show...
Last updated: January 14, 2026
CLI Commands
Complete reference for BlockSecOps CLI commands.
Global Options
These options work with all commands:
| Option | Description |
|---|---|
--help |
Show help message |
--install-completion |
Install shell completion |
--show-completion |
Show completion script |
Authentication Commands
blocksecops auth login
Authenticate with the BlockSecOps API.
blocksecops auth login [OPTIONS]
Options:
| Option | Type | Description |
|---|---|---|
--api-key, -k |
string | API key (prompts if not provided) |
--api-url, -u |
string | API URL (saves to config) |
Examples:
# Interactive login (prompts for key)
blocksecops auth login
# Login with key directly
blocksecops auth login --api-key bso_live_abc123...
# Login to custom instance
blocksecops auth login --api-url https://blocksecops.company.com
blocksecops auth logout
Remove stored credentials.
blocksecops auth logout
Removes the API key from:
- System keyring
- File-based storage (if used)
blocksecops auth whoami
Show current user information.
blocksecops auth whoami
Output:
┌──────────────────────────────────────────────────────────────┐
│ Current User │
│ │
│ Email: [email protected] │
│ User ID: 529f5865-6107-4636-bf88-e044e1cfaafc │
│ Plan: professional │
│ API URL: https://api.blocksecops.com │
└──────────────────────────────────────────────────────────────┘
blocksecops auth status
Check authentication status and API connectivity.
blocksecops auth status
Output (authenticated):
API URL: https://api.blocksecops.com
Status: Authenticated as [email protected]
Output (not authenticated):
API URL: https://api.blocksecops.com
Status: Not authenticated
Run 'blocksecops auth login' to authenticate
Scan Commands
blocksecops scan run
Scan a smart contract file or directory.
blocksecops scan run <PATH> [OPTIONS]
Arguments:
| Argument | Required | Description |
|---|---|---|
PATH |
Yes | Path to contract file or directory |
Options:
| Option | Type | Default | Description |
|---|---|---|---|
--wait, -w |
flag | true |
Wait for scan completion |
--no-wait, -W |
flag | - | Start scan and return immediately |
--output, -o |
string | table |
Output format: table, json, sarif, junit |
--scanner, -s |
string[] | all | Specific scanners to use (repeatable) |
--fail-on |
string | - | Exit code 1 if severity >= threshold |
--output-file, -f |
path | - | Write output to file |
Exit Codes:
| Code | Meaning |
|---|---|
| 0 | Success (no vulnerabilities above threshold) |
| 1 | Vulnerabilities found above --fail-on threshold |
| 1 | Scan failed or error |
Examples:
# Basic scan
blocksecops scan run contract.sol
# Scan with JSON output
blocksecops scan run contract.sol --output json
# Scan with specific scanners
blocksecops scan run contract.sol --scanner slither --scanner aderyn
# CI pipeline: fail on high severity
blocksecops scan run ./contracts --fail-on high --output sarif
# Save results to file
blocksecops scan run contract.sol --output sarif --output-file results.sarif
# Start scan without waiting
blocksecops scan run contract.sol --no-wait
# Returns scan ID to check later
blocksecops scan status
Check the status of a scan.
blocksecops scan status <SCAN_ID>
Arguments:
| Argument | Required | Description |
|---|---|---|
SCAN_ID |
Yes | UUID of the scan |
Output:
Scan ID: 2bff4881-edc1-46c1-b8f1-7c30960d8357
Status: COMPLETED
Started: 2026-01-04 10:30:00
Completed: 2026-01-04 10:31:45
Status Values:
| Status | Description |
|---|---|
pending |
Scan queued |
running |
Scan in progress |
completed |
Scan finished successfully |
failed |
Scan encountered an error |
cancelled |
Scan was cancelled |
blocksecops scan results
Get results for a completed scan.
blocksecops scan results <SCAN_ID> [OPTIONS]
Arguments:
| Argument | Required | Description |
|---|---|---|
SCAN_ID |
Yes | UUID of the scan |
Options:
| Option | Type | Default | Description |
|---|---|---|---|
--output, -o |
string | table |
Output format |
--output-file, -f |
path | - | Write to file |
--fail-on |
string | - | Exit code 1 if severity >= threshold |
Examples:
# View results in table format
blocksecops scan results 2bff4881-edc1-46c1-b8f1-7c30960d8357
# Export as SARIF
blocksecops scan results 2bff4881... --output sarif --output-file results.sarif
# Check if any high severity issues
blocksecops scan results 2bff4881... --fail-on high && echo "No high severity issues"
blocksecops scan list
List recent contracts and scans.
blocksecops scan list [OPTIONS]
Options:
| Option | Type | Default | Description |
|---|---|---|---|
--limit, -n |
int | 10 |
Number of items to show |
Output:
Recent Contracts
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ Name ┃ Network ┃ Created ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ 2bff4881 │ Vault.sol │ ethereum │ 2026-01-04 10:30 │
│ a3c12f9e │ Token.sol │ ethereum │ 2026-01-03 15:22 │
│ 87d4e2b1 │ Staking.sol │ polygon │ 2026-01-02 09:15 │
└──────────┴─────────────────┴──────────┴──────────────────┘
Other Commands
blocksecops version
Show CLI version information.
blocksecops version
Output:
blocksecops-cli version 0.1.0
Usage Patterns
Quick Scan
blocksecops scan run contract.sol
CI Pipeline
blocksecops scan run ./contracts \
--output sarif \
--output-file results.sarif \
--fail-on high
Async Workflow
# Start scan
SCAN_ID=$(blocksecops scan run contract.sol --no-wait --output json | jq -r '.scan.id')
# Do other work...
# Check status later
blocksecops scan status $SCAN_ID
# Get results when done
blocksecops scan results $SCAN_ID --output json
Multiple Scanners
blocksecops scan run contract.sol \
--scanner slither \
--scanner aderyn \
--scanner mythril
Export for GitHub Code Scanning
blocksecops scan run ./contracts \
--output sarif \
--output-file results.sarif
# Upload to GitHub
gh api repos/{owner}/{repo}/code-scanning/sarifs \
-X POST \
-F [email protected]
Error Messages
Authentication Required
Not authenticated. Run 'blocksecops auth login' first.
Solution: Run blocksecops auth login
Invalid API Key
Authentication error: Authentication failed. Please run 'blocksecops auth login'.
Solution: Verify your API key in the dashboard and login again.
Scan Failed
Scan failed: Contract compilation error
Solution: Check that your contract compiles successfully locally.
File Not Found
Error: Path not found: contract.sol
Solution: Verify the file path exists.
Shell Completion
Install tab completion for your shell:
# Bash
blocksecops --install-completion bash
# Zsh
blocksecops --install-completion zsh
# Fish
blocksecops --install-completion fish
After installation, restart your shell or source your profile.
Next Steps
- CLI Configuration - Configure defaults
- Output Formats - Format options
- Pre-Commit Hooks - Git integration