Initial API Configuration

SCANOSS tools function without additional configuration and do not require an API key. However, an API key enables access to additional API features.

Environment Variables

Set your API key as an environment variable to make it available across all SCANOSS CLI tools:

macOS / Linux:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export SCANOSS_API_KEY=your_api_key_here' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell):

# Set for current session only
$env:SCANOSS_API_KEY = "your_api_key_here"

# Set permanently for the current user
[System.Environment]::SetEnvironmentVariable('SCANOSS_API_KEY', 'your_api_key_here', 'User')

Note: After setting a permanent environment variable on Windows, open a new terminal session for the change to take effect. On macOS/Linux, run source ~/.bashrc (or the relevant profile file) or open a new terminal session.

SCANOSS-PY

To use the SCANOSS Python CLI, install it following the instructions in the repository, then run a scan using one of the commands below.

Basic scan (no API key required):

# macOS / Linux
scanoss-py scan -o results.json /path/to/code

# Windows (PowerShell)
scanoss-py scan -o results.json C:\path\to\code

With API key via environment variable:

# macOS / Linux
scanoss-py scan --key $SCANOSS_API_KEY -o results.json /path/to/code

# Windows (PowerShell)
scanoss-py scan --key $env:SCANOSS_API_KEY -o results.json C:\path\to\code

SCANOSS-JS

To use the SCANOSS JavaScript CLI, install it following the instructions in the repository, then run a scan using one of the commands below.

Basic scan (no API key required):

# macOS / Linux
scanoss-js scan /path/to/code

# Windows (PowerShell)
scanoss-js scan C:\path\to\code

With API key via environment variable:

# macOS / Linux
scanoss-js scan --key $SCANOSS_API_KEY -o results.json /path/to/code

# Windows (PowerShell)
scanoss-js scan --key $env:SCANOSS_API_KEY -o results.json C:\path\to\code

SCANOSS-CC

SCANOSS Code Compare communicates directly with the SCANOSS API and requires an API key to be configured before use.

Configure with API key via environment variable:

# macOS / Linux
scanoss-cc configure --apiUrl https://api.scanoss.com --key $SCANOSS_API_KEY

# Windows (PowerShell)
scanoss-cc configure --apiUrl https://api.scanoss.com --key $env:SCANOSS_API_KEY

Note: The --apiUrl flag value is case-sensitive. Use the URL exactly as shown above.

Verify your configuration:

Configuration settings are stored in the following file, depending on your operating system:

• macOS / Linux: ~/.scanoss/scanoss-cc-settings.json
• Windows: %USERPROFILE%\.scanoss\scanoss-cc-settings.json

Inspect this file to confirm that your API key has been saved correctly:

# macOS / Linux
cat ~/.scanoss/scanoss-cc-settings.json

# Windows (PowerShell)
Get-Content "$env:USERPROFILE\.scanoss\scanoss-cc-settings.json"

SBOM Workbench

The SBOM Workbench can be configured to use your API key via the application settings:

1. Navigate to File → Settings
2. Add a new API key entry by clicking the ’+’ button
3. Complete the form with the following values:
   • Base URL: https://api.scanoss.com
   • API Key: your API key value

Once the API key has been saved, subsequent scans will be submitted to the SCANOSS API rather than processed locally.

For further assistance, refer to the FAQs.