OmniAudit Local CLI

Command-line interface for OmniAudit smart contract security scanner with local execution and connector session support.

Requirements

Before installing, ensure you have:

• Node.js >= 14.0.0
• npm >= 6.0.0
• Python >= 3.6
• Slither Analyzer: Install with pip install slither-analyzer
• Solidity Compiler (solc) - Any of:
  • solc (system installation)
  • solc-select (version manager)
  • Foundry (forge)
  • Hardhat (project dependency)

Verify installations:

node --version
python3 --version
slither --version

Installation

Global Installation (Recommended)

Install globally via npm:

npm install -g omniaudit-localhost

After installation, the omniaudit-localhost command will be available globally.

Using npx (No Installation Required)

You can also use npx to run the CLI without installing:

npx omniaudit-localhost --id <connectorId> --path ./contracts --server http://localhost:5000

Local Development

For local development or testing:

cd cli/omni-cli
npm install
npm link  # Makes 'omniaudit-localhost' command available globally for testing

Usage

One-Shot Mode (Scan and Exit)

Run a scan immediately and exit. Perfect for CI/CD pipelines:

# Basic usage with connector ID from web UI (backend URL auto-detected)
omniaudit-localhost --id <connectorId> --path ./contracts

# Example
npx omniaudit-localhost --id abc123xyz --path ./contracts

# With custom backend URL (optional)
omniaudit-localhost --id <connectorId> --path ./contracts --server https://api.omniaudit.com

One-Shot Mode Options:

• --id <connectorId> - Required - Connector session ID from OmniAudit web UI
• --path <directory> - Required - Directory containing Solidity contracts to scan
• --server <url> - Optional - Backend server URL (auto-detected if not provided)

Server Mode (Persistent HTTP Server)

Start a persistent HTTP server that listens for scan requests:

# Start server (no --path flag, backend URL auto-detected)
omniaudit-localhost --id <connectorId>

# Or without connector ID (uses device token auth)
omniaudit-localhost

# With custom backend URL (optional)
omniaudit-localhost --server https://api.omniaudit.com

The server will:

• Start on http://localhost:9620
• Accept scan requests from the web UI
• Poll for remote scan jobs from the backend
• Maintain scan history in local database

Server Mode Options:

• --id <connectorId> - Optional - Link to connector session from web UI
• --server <url> - Optional - Backend server URL (auto-detected if not provided)

Help

View all available options:

omniaudit-localhost --help

Options

Global Options

• --id <connectorId> - Connector session ID from OmniAudit web UI (required for one-shot mode)
• --path <directory> - Directory to scan (enables one-shot mode, exits after scan)
• --server <url> - Optional - Backend server URL (auto-detected if not provided)
• --help - Show help message

Backend URL Auto-Detection

The CLI automatically detects the backend URL using this priority:

1. Environment Variable: OMNIAUDIT_BACKEND (highest priority)
2. Production Mode: If NODE_ENV=production, defaults to https://api.omniaudit.com
3. Development Mode: Defaults to http://localhost:5000
4. Manual Override: Use --server <url> to override

Examples:

# Use environment variable
export OMNIAUDIT_BACKEND=https://api.omniaudit.com
omniaudit-localhost --id abc123 --path ./contracts

# Production mode (auto-detects production URL)
NODE_ENV=production omniaudit-localhost --id abc123 --path ./contracts

# Development mode (defaults to localhost)
omniaudit-localhost --id abc123 --path ./contracts

# Manual override
omniaudit-localhost --id abc123 --path ./contracts --server https://custom-api.com

One-Shot Mode Behavior

When --path is provided:

1. CLI validates that --id is also provided
2. Scans the specified directory
3. Uploads results to backend server
4. Exits with code 0 (success) or 1 (error)

Server Mode Behavior

When --path is NOT provided:

1. Starts HTTP server on port 9620
2. Links to connector session if --id provided
3. Accepts scan requests via HTTP API
4. Polls backend for remote scan jobs
5. Runs until interrupted (Ctrl+C)

Configuration

Token is stored in ~/.omni-cli/config.json:

{
  "token": "your-jwt-token",
  "apiUrl": "http://localhost:5000",
  "updatedAt": "2025-11-26T..."
}

Auto-Detection

The CLI automatically detects:

• Slither (venv or system)
• solc (Solidity compiler)
• solc-select
• Foundry (forge)
• Hardhat

Examples

One-Shot Mode Examples

# Basic one-shot scan with connector ID (backend URL auto-detected)
npx omniaudit-localhost --id abc123xyz --path ./contracts

# Using npx (no installation needed)
npx omniaudit-localhost --id abc123xyz --path ./contracts

# With custom backend URL (optional)
omniaudit-localhost --id abc123xyz --path ./contracts --server https://api.omniaudit.com

# Using environment variable
export OMNIAUDIT_BACKEND=https://api.omniaudit.com
omniaudit-localhost --id abc123xyz --path ./contracts

Server Mode Examples

# Start server with connector session (backend URL auto-detected)
omniaudit-localhost --id abc123xyz

# Start server without connector (device token auth)
omniaudit-localhost

# With custom backend URL (optional)
omniaudit-localhost --server https://api.omniaudit.com

# Server will be available at http://localhost:9620

Integration with Web UI

1. Open OmniAudit web dashboard
2. Click "Connect Local Host" button
3. Copy the connector ID shown in the modal
4. Run the CLI command with the connector ID:

npx omniaudit-localhost --id <connectorId> --path ./contracts

Note: The --server flag is optional. The CLI automatically detects the backend URL from environment variables or uses smart defaults.

The web UI will automatically detect when the scan completes and update the dashboard.

Troubleshooting

Slither not found

Error: Slither executable not found

Solution:

Install Slither:

pip install slither-analyzer

Or with Python 3 explicitly:

pip3 install slither-analyzer

Verify installation:

slither --version

If using virtual environment:

Activate venv first:

source venv/bin/activate  # Linux/Mac

or

venv\Scripts\activate  # Windows

Then install:

pip install slither-analyzer

Connection refused to backend

Error: ECONNREFUSED or Cannot connect to server

Solution:

• Check backend server is running:

curl http://localhost:5000/health

• Verify --server URL is correct
• Check firewall/network settings
• Try with explicit server URL (if auto-detection fails):

omniaudit-localhost --id abc123 --path ./contracts --server http://localhost:5000

• Or set environment variable:

export OMNIAUDIT_BACKEND=http://localhost:5000
omniaudit-localhost --id abc123 --path ./contracts

Invalid connector ID

Error: Invalid or expired connector ID

Solution:

• Connector IDs expire in 15 minutes
• Generate new ID:
  1. Go to OmniAudit Dashboard
  2. Click "Connect Local Host"
  3. Copy fresh connector ID
  4. Run command immediately

Permission denied (Linux/Mac)

Error: EACCES: permission denied

Solution:

Make CLI executable:

chmod +x $(which omniaudit-localhost)

Or reinstall with sudo:

sudo npm install -g omniaudit-localhost

Port 9620 already in use (Server mode)

Error: EADDRINUSE: address already in use :::9620

Solution:

Find and kill existing process:

lsof -ti:9620 | xargs kill -9

Or on Windows:

netstat -ano | findstr :9620
taskkill /PID <PID> /F

Then restart CLI:

omniaudit-localhost

solc compiler not found

Error: Solidity compiler not detected

Solution:

Option 1 - Install solc directly:

npm install -g solc

Option 2 - Use solc-select:

pip install solc-select
solc-select install 0.8.19
solc-select use 0.8.19

Option 3 - Use Foundry:

curl -L https://foundry.paradigm.xyz | bash
foundryup

No contracts found in path

Error: No .sol files found in directory

Solution:

• Verify path is correct:

ls -la ./contracts/*.sol

• Use absolute path:

omniaudit-localhost --id abc123 --path /full/path/to/contracts

• Ensure .sol extension present

npm WARN deprecated

Warning during installation (safe to ignore):

npm WARN deprecated <package>

Solution:

• These are dependency warnings, CLI will work fine
• Update to latest version periodically:

npm update -g omniaudit-localhost