CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-safety

Scan dependencies for known vulnerabilities and licenses.

Overall
score

61%

Overview
Eval results
Files

cli-commands.mddocs/

CLI Commands Reference

Safety CLI provides a comprehensive set of commands for vulnerability scanning, authentication, and project management. All commands are accessed through the safety entry point.

Command Structure

safety [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]

Global Options { .api }

--debug                        # Enable debug logging
--disable-optional-telemetry   # Disable telemetry collection
--help                         # Show help message
--version                      # Show version information

Import Statement:

from safety.cli import cli

Core Commands

Vulnerability Scanning

safety scan { .api }

Description: Scan project dependencies for known vulnerabilities (primary command).

Usage:

safety scan [OPTIONS] [TARGET]

Parameters:

  • TARGET (Path, optional): Directory to scan (default: current directory)

Options:

--output {screen,json}           # Output format (default: screen)
--detailed-output               # Show detailed vulnerability information  
--save-as FORMAT:FILE           # Save report to file with format
--policy-file PATH              # Path to policy file (.safety-policy.yml)
--apply-fixes                   # Apply automatic fixes when available
--max-fixes N                   # Maximum number of fixes to apply
--no-audit                      # Skip audit and monitoring
--short-report                  # Generate short vulnerability report
--continue-on-error             # Continue scan even if errors occur

Examples:

# Scan current directory
safety scan

# Scan specific path with JSON output
safety scan /path/to/project --output json

# Scan with policy file
safety scan --policy-file .safety-policy.yml

# Save detailed report to file
safety scan --detailed-output --save-as json:report.json

Python API:

# Note: CLI commands are typically accessed through the main CLI interface
from safety.cli import cli
import sys

# Programmatic CLI invocation (recommended approach)
sys.argv = ['safety', 'scan', '--detailed-output']
cli()

safety system-scan { .api }

Description: Scan system-wide Python packages for vulnerabilities.

Usage:

safety system-scan [OPTIONS]

Options:

--target PATH                   # Specific target path to scan (can be used multiple times)
--output {screen,json}           # Output format (default: screen)
--detailed-output               # Show detailed vulnerability information
--save-as FORMAT:FILE           # Save report to file with format  
--policy-file PATH              # Path to policy file
--short-report                  # Generate short vulnerability report
--continue-on-error             # Continue scan even if errors occur

Examples:

# Scan system packages
safety system-scan

# System scan with JSON output
safety system-scan --output json --save-as json:system-report.json

safety check (Deprecated) { .api }

Description: Legacy vulnerability check command (deprecated, use scan instead).

Usage:

safety check [OPTIONS] [FILES]

Deprecation Notice: This command will be unsupported beyond June 1, 2024. Use safety scan instead.

Options:

--db PATH                       # Path to vulnerability database
--full-report                   # Show full report details
--stdin                         # Read from stdin
--files FILE [FILE ...]         # Specific files to check
--cache                         # Use cached database
--ignore VULN_ID               # Ignore specific vulnerabilities
--ignore-unpinned-requirements  # Ignore unpinned requirements
--output {text,json,html,bare}  # Output format
--json                         # JSON output (alias)
--html                         # HTML output (alias)  
--bare                         # Minimal output (alias)
--exit-code                    # Exit with error code on vulnerabilities
--policy-file PATH             # Path to policy file
--audit-and-monitor            # Enable audit and monitoring
--project NAME                 # Project name for reporting
--save-json PATH               # Save JSON report
--save-html PATH               # Save HTML report
--apply-remediations           # Apply automatic remediations
--auto-remediation-limit N     # Limit automatic remediations
--no-prompt                    # Skip interactive prompts
--json-version VERSION         # JSON schema version

License Management

safety license { .api }

Description: Find open source licenses used by Python dependencies.

Usage:

safety license [OPTIONS] [FILES]

Options:

--db PATH                      # Path to license database
--output {text,json}           # Output format (default: text)
--cache                        # Use cached database
--files FILE [FILE ...]        # Specific files to check

Examples:

# Check licenses in requirements.txt
safety license --files requirements.txt

# Check licenses with JSON output  
safety license --output json

# Use custom license database
safety license --db /path/to/license_db

Authentication Commands

safety auth login { .api }

Description: Authenticate with Safety platform using browser-based OAuth flow.

Usage:

safety auth login [OPTIONS]

Options:

--headless                     # Run in headless mode (copy/paste URL)

Examples:

# Interactive browser login
safety auth login

# Headless login (for CI/CD environments)
safety auth login --headless

Python API:

from safety.auth.cli import login
import typer

# Create context and authenticate
ctx = typer.Context(login)
login(ctx=ctx, headless=False)

safety auth logout { .api }

Description: Sign out from Safety platform.

Usage:

safety auth logout

safety auth status { .api }

Description: Check current authentication status and organization details.

Usage:

safety auth status

Output includes:

  • Authentication status
  • Organization information
  • Account details
  • Current CLI version
  • Latest available version

safety auth register { .api }

Description: Register a new Safety platform account.

Usage:

safety auth register

Project Initialization

safety init { .api }

Description: Initialize Safety configuration in a project.

Usage:

safety init [OPTIONS]

Options:

--policy-file PATH             # Path for generated policy file
--interactive                  # Interactive configuration setup

Policy and Configuration

safety generate policy { .api }

Description: Generate a Safety policy template file.

Usage:

safety generate policy [OPTIONS] NAME

Parameters:

  • NAME (str, required): Name for the generated policy

Options:

--path PATH                    # Directory to create policy file (default: .)
--minimum-cvss-severity LEVEL  # Minimum CVSS severity level (default: critical)

Severity Levels:

  • critical
  • high
  • medium
  • low

Examples:

# Generate basic policy template
safety generate policy my-project

# Generate with custom path and severity
safety generate policy my-project --path ./config --minimum-cvss-severity high

safety generate installation_policy { .api }

Description: Generate an installation policy for package management.

Usage:

safety generate installation_policy [OPTIONS] NAME

Parameters:

  • NAME (str, required): Name for the generated installation policy

Options:

--path PATH                    # Directory to create policy file (default: .)
--minimum-cvss-severity LEVEL  # Minimum CVSS severity level (default: critical)

safety validate { .api }

Description: Validate Safety policy file syntax and structure.

Usage:

safety validate [OPTIONS] NAME VERSION

Parameters:

  • NAME (str, required): Policy name to validate
  • VERSION (str, required): Policy version to validate

Options:

--path PATH                    # Path to policy file directory (default: .)

Configuration Management

safety configure { .api }

Description: Configure Safety CLI settings and proxy options.

Usage:

safety configure [OPTIONS]

Options:

--proxy-protocol {http,https}  # Proxy protocol
--proxy-host HOST              # Proxy hostname
--proxy-port PORT              # Proxy port number
--proxy-required               # Require proxy for all requests
--proxy-timeout SECONDS        # Proxy timeout in seconds
--organization-id ID           # Organization ID
--organization-name NAME       # Organization name
--save-to-system              # Save configuration system-wide

Examples:

# Configure HTTP proxy
safety configure --proxy-protocol http --proxy-host proxy.company.com --proxy-port 8080

# Set organization settings
safety configure --organization-id 12345 --organization-name "My Company"

# Save configuration system-wide
safety configure --save-to-system

Update Management

safety check-updates { .api }

Description: Check for Safety CLI updates and configuration changes.

Usage:

safety check-updates [OPTIONS]

Options:

--output {screen,json}         # Output format (default: screen)

Output includes:

  • Current Safety version
  • Latest available version
  • Organization information
  • Account status
  • Configuration updates

Advanced Commands

safety codebase { .api }

Description: Advanced codebase analysis and scanning features.

Usage:

safety codebase [SUBCOMMAND] [OPTIONS]

safety firewall { .api }

Description: Network security and firewall-related features.

Usage:

safety firewall [SUBCOMMAND] [OPTIONS]

Exit Codes { .api }

Safety CLI uses standard exit codes to indicate command results:

from safety.constants import (
    EXIT_CODE_OK,                    # 0 - Success
    EXIT_CODE_FAILURE,              # 1 - General failure  
    EXIT_CODE_VULNERABILITIES_FOUND, # 64 - Vulnerabilities found
    EXIT_CODE_INVALID_AUTH_CREDENTIAL, # 65 - Invalid authentication credential
    EXIT_CODE_TOO_MANY_REQUESTS,    # 66 - Too many requests (rate limited)
    EXIT_CODE_UNABLE_TO_LOAD_LOCAL_VULNERABILITY_DB, # 67 - Cannot load local DB
    EXIT_CODE_UNABLE_TO_FETCH_VULNERABILITY_DB, # 68 - Cannot fetch DB
    EXIT_CODE_MALFORMED_DB,         # 69 - Database is malformed
    EXIT_CODE_INVALID_PROVIDED_REPORT, # 70 - Invalid report provided
    EXIT_CODE_INVALID_REQUIREMENT,  # 71 - Invalid requirement specification
    EXIT_CODE_EMAIL_NOT_VERIFIED    # 72 - Email not verified
)
  • 0: Command executed successfully, no vulnerabilities found
  • 1: Command failed due to error or invalid usage
  • 64: Vulnerabilities were found in the scan
  • 65: Invalid authentication credential provided
  • 66: Too many requests sent to API (rate limited)
  • 67: Unable to load local vulnerability database
  • 68: Unable to fetch vulnerability database from remote
  • 69: Vulnerability database is malformed or corrupted
  • 70: Invalid report format or content provided
  • 71: Invalid requirement specification in files
  • 72: Email address not verified for account

Command Aliases and Shortcuts { .api }

# Output format aliases
--json          # Equivalent to --output json
--html          # Equivalent to --output html (check command)
--bare          # Equivalent to --output bare (check command)

Environment Variables { .api }

Safety CLI respects several environment variables for configuration:

SAFETY_API_BASE_URL         # Base URL for Safety API
SAFETY_DB_MIRROR           # Mirror URL for vulnerability database
SAFETY_PROXY_HOST          # Proxy hostname
SAFETY_PROXY_PORT          # Proxy port  
SAFETY_PROXY_PROTOCOL      # Proxy protocol (http/https)
SAFETY_OS_DESCRIPTION      # Operating system description override

Common Usage Patterns

CI/CD Integration

# Basic CI vulnerability check
safety scan --output json --continue-on-error

# Authenticated scan with policy
safety auth login --headless
safety scan --policy-file .safety-policy.yml --exit-code

# System-wide scanning in containers
safety system-scan --output json --save-as json:/tmp/scan-report.json

Development Workflow

# Initialize project with Safety
safety init --interactive
safety generate policy myproject

# Regular development scanning
safety scan --detailed-output
safety license --output json

# Pre-deployment checks
safety scan --policy-file .safety-policy.yml --apply-fixes --max-fixes 5

Reporting and Automation

# Generate comprehensive reports
safety scan --detailed-output --save-as json:vulnerability-report.json
safety license --output json > license-report.json

# Automated policy validation  
safety validate myproject 1.0 --path ./policies

This comprehensive CLI reference covers all available commands, options, and usage patterns for Safety CLI, enabling developers to effectively integrate vulnerability scanning into their development and deployment workflows.

Install with Tessl CLI

npx tessl i tessl/pypi-safety

docs

authentication.md

cli-commands.md

configuration.md

errors.md

formatters.md

index.md

models.md

programmatic.md

scanning.md

tile.json