CLI Configuration

Configure the BlockSecOps CLI for your workflow.

Configuration Hierarchy

Settings are resolved in this order (highest priority first):

Command-line flags - --api-url, --output, etc.
Environment variables - BLOCKSECOPS_API_KEY, etc.
Configuration file - ~/.blocksecops/config.json
Default values

Configuration File

Location

OS	Path
Linux/macOS	`~/.blocksecops/config.json`
Windows	`%APPDATA%\blocksecops\config.json`

Format

{
  "api_url": "https://api.blocksecops.com",
  "default_output": "table",
  "default_severity_threshold": "high",
  "ci_mode": false,
  "color": true
}

Settings

Setting	Type	Default	Description
`api_url`	string	`https://api.blocksecops.com`	API endpoint URL
`default_output`	string	`table`	Default output format
`default_severity_threshold`	string	`high`	Default `--fail-on` value
`ci_mode`	boolean	`false`	Enable CI mode
`color`	boolean	`true`	Enable colored output

Environment Variables

Authentication

Variable	Description
`BLOCKSECOPS_API_KEY`	API key for authentication
`BLOCKSECOPS_API_URL`	Override API endpoint URL

Behavior

Variable	Description
`CI`	Set to `true` to enable CI mode
`NO_COLOR`	Set to disable colored output
`BLOCKSECOPS_FAIL_ON`	Default severity threshold for hooks
`BLOCKSECOPS_TIMEOUT`	Default scan timeout (seconds)
`BLOCKSECOPS_OUTPUT`	Default output format

Example: CI Environment

export BLOCKSECOPS_API_KEY="bso_live_abc123..."
export CI=true
export BLOCKSECOPS_FAIL_ON=high

blocksecops scan run ./contracts

API Key Storage

System Keyring (Default)

API keys are stored securely in your system keyring:

OS	Backend
macOS	Keychain
Linux	Secret Service (GNOME Keyring, KWallet)
Windows	Windows Credential Manager

# Store API key in keyring
blocksecops auth login

# Remove from keyring
blocksecops auth logout

Environment Variable

For CI/CD or containers, use environment variable:

export BLOCKSECOPS_API_KEY="bso_live_abc123..."

File-Based Fallback

If keyring is unavailable, key is stored in:

~/.blocksecops/.api_key

This file is created with 600 permissions (owner read/write only).

Setting API URL

For Development/Testing

# Via flag
blocksecops auth login --api-url http://localhost:8000

# Via environment
export BLOCKSECOPS_API_URL=http://localhost:8000
blocksecops auth login

Self-Hosted Instance

# Set permanently
blocksecops auth login --api-url https://blocksecops.internal.company.com

This saves the URL to config.json.

Output Configuration

Default Output Format

{
  "default_output": "json"
}

Or via environment:

export BLOCKSECOPS_OUTPUT=json

Disable Colors

# Via environment
export NO_COLOR=1

# Or in config
{
  "color": false
}

CI Mode

CI mode optimizes output for pipelines:

Disables interactive prompts
Disables color if terminal doesn't support it
Outputs machine-readable error messages

Enable CI Mode

Automatic when CI=true:

export CI=true
blocksecops scan run ./contracts

Or in config:

{
  "ci_mode": true
}

Proxy Configuration

The CLI respects standard proxy environment variables:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

blocksecops scan run ./contracts

Timeout Configuration

Scan Timeout

Default scan timeout is 10 minutes (600 seconds).

# Via environment (for pre-commit hooks)
export BLOCKSECOPS_TIMEOUT=300  # 5 minutes

Configuration Examples

Personal Development

~/.blocksecops/config.json:

{
  "api_url": "https://api.blocksecops.com",
  "default_output": "table",
  "default_severity_threshold": "medium",
  "color": true
}

CI Pipeline

# Environment variables (set in CI secrets)
BLOCKSECOPS_API_KEY=bso_live_abc123...
CI=true

# Command
blocksecops scan run ./contracts \
  --output sarif \
  --output-file results.sarif \
  --fail-on high

Self-Hosted Enterprise

~/.blocksecops/config.json:

{
  "api_url": "https://blocksecops.internal.company.com",
  "default_output": "json",
  "default_severity_threshold": "high",
  "ci_mode": false
}

Resetting Configuration

Clear All Settings

rm -rf ~/.blocksecops/
blocksecops auth logout

Reset API Key Only

blocksecops auth logout
blocksecops auth login

Troubleshooting

Keyring Not Available

If you see "keyring not available" errors:

# Linux: Install keyring backend
pip install keyrings.alt

# Or use environment variable instead
export BLOCKSECOPS_API_KEY=your_key

Configuration Not Loading

Check file permissions:

ls -la ~/.blocksecops/
# Should show: drwx------ (700) for directory
# Should show: -rw------- (600) for files

API Connection Issues

Test connectivity:

blocksecops auth status

Check proxy settings if behind corporate firewall.

Next Steps

CLI Commands - Command reference
Output Formats - Format options
Pre-Commit Hooks - Git integration