CLI Issues

Troubleshooting guide for the BlockSecOps CLI tool.

Installation Issues

"Command not found: blocksecops"

Cause: CLI not installed or not in PATH.

Solutions:

Install the CLI:
```
pip install blocksecops-cli
```
Check installation:
```
pip show blocksecops-cli
```
Run as module instead:
```
python -m blocksecops_cli --help
```

Check PATH includes pip bin directory:

# Linux/macOS
export PATH="$HOME/.local/bin:$PATH"

# Or use pipx for isolated install
pipx install blocksecops-cli

"ModuleNotFoundError: No module named 'blocksecops_cli'"

Cause: Package not installed in the current Python environment.

Solutions:

Check you're using the right Python:
```
which python
pip --version
```
Install in current environment:
```
pip install blocksecops-cli
```

Use virtual environment:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
pip install blocksecops-cli

"Permission denied" during install

Cause: Installing to system Python without sudo.

Solutions:

Install for user only (recommended):
```
pip install --user blocksecops-cli
```
Use pipx (recommended for CLI tools):
```
pipx install blocksecops-cli
```

Use virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install blocksecops-cli

Authentication Issues

"Not authenticated"

Error:

Not authenticated. Run 'blocksecops auth login' first.

Solution:

blocksecops auth login

Enter your API key when prompted. Get an API key from Settings > API Keys in the dashboard.

"Authentication failed"

Error:

Authentication error: Authentication failed. Please run 'blocksecops auth login'.

Causes:

Invalid API key
Expired API key
Revoked API key

Solutions:

Verify your API key in the dashboard:
- Go to Settings > API Keys
- Check key is active and not expired

Login again:

blocksecops auth logout
blocksecops auth login

Create a new API key if needed

"Connection refused" or "Network error"

Cause: Cannot reach BlockSecOps API.

Solutions:

Check internet connection:

curl https://api.blocksecops.com/health

Check for proxy/firewall issues:

# If behind proxy
export HTTPS_PROXY=http://proxy.company.com:8080

Verify API URL:
```
blocksecops auth status
```

API key not saved / Keyring errors

Error:

Failed to store credentials in keyring

Cause: System keyring not available or not configured.

Solutions:

Use environment variable instead:

export BLOCKSECOPS_API_KEY="your-api-key"
blocksecops scan run contract.sol

Install keyring backend:

# Linux
pip install keyring keyrings.alt

# macOS (usually works out of box)
# Windows (usually works out of box)

Check keyring status:

python -c "import keyring; print(keyring.get_keyring())"

Scan Issues

"Path not found"

Error:

Error: Path not found: contract.sol

Solution:

Verify the file exists:

ls -la contract.sol

# Use full path if needed
blocksecops scan run /path/to/contract.sol

"Scan failed: Contract compilation error"

Cause: Contract has syntax errors or missing dependencies.

Solutions:

Verify contract compiles locally:

# Using solc
solc --version
solc contract.sol

# Using Foundry
forge build

# Using Hardhat
npx hardhat compile

Include all imports:
- Upload the entire project directory
- Or use --include to specify dependency paths
Check Solidity version:
- Ensure pragma version is supported
- BlockSecOps supports Solidity 0.4.x - 0.8.x

Scan timeout in CI

Cause: Scan taking longer than CI timeout.

Solutions:

Use async scan:

# Start scan without waiting
SCAN_ID=$(blocksecops scan run contract.sol --no-wait --output json | jq -r '.scan_id')

# Check later
blocksecops scan status $SCAN_ID
blocksecops scan results $SCAN_ID

Increase CI timeout:

# GitHub Actions
- name: Security Scan
  timeout-minutes: 30
  run: blocksecops scan run ./contracts

Use fewer scanners for quick checks:

blocksecops scan run contract.sol --scanner slither

Output Issues

SARIF file not generated

Solution:

Use --output-file to specify output path:

blocksecops scan run contract.sol --output sarif --output-file results.sarif

Verify file was created:

ls -la results.sarif
cat results.sarif | jq '.runs[0].results | length'

JSON output not valid

Cause: Extra output mixed with JSON.

Solution:

Use --output json with quiet mode:

blocksecops scan run contract.sol --output json 2>/dev/null

Or save to file:

blocksecops scan run contract.sol --output json --output-file results.json

Exit code not working in CI

Cause: --fail-on not specified or threshold not met.

Solution:

Specify threshold:

# Fail on high or critical
blocksecops scan run contract.sol --fail-on high
echo "Exit code: $?"

# Fail only on critical
blocksecops scan run contract.sol --fail-on critical
echo "Exit code: $?"

Exit codes:

0 - Success, no issues above threshold
1 - Issues found above threshold, or error occurred

Environment Issues

Wrong Python version

Error:

Python 3.9 or higher is required

Solution:

Check Python version:

python --version
python3 --version

Install Python 3.10+:

# macOS
brew install [email protected]

# Ubuntu
sudo apt install python3.11

# Use specific version
python3.11 -m pip install blocksecops-cli

Conflicts with other packages

Solution:

Use isolated environment:

# pipx (recommended for CLI tools)
pipx install blocksecops-cli

# Or virtual environment
python -m venv blocksecops-env
source blocksecops-env/bin/activate
pip install blocksecops-cli

Getting Help

Check CLI version

blocksecops version

Check authentication status

blocksecops auth status

Enable debug output

# Set environment variable
export BLOCKSECOPS_DEBUG=1
blocksecops scan run contract.sol

Contact Support

If issues persist:

Note the exact error message
Include CLI version (blocksecops version)
Include Python version (python --version)
Include OS (macOS, Linux, Windows)
Contact [email protected]

Next Steps

CLI Overview - Installation guide
CLI Commands - Command reference
Contact Support - Get help