Commands

Complete reference for all sus CLI commands

sus init

Initialize sus in your project with optional AGENTS.md docs index.

sus init

Flags:

Examples:

# Interactive initialization
sus init
 
# Non-interactive with defaults
sus init -y

Output:

$ sus init
 
  🔧 initializing sus...
 
  Enable AGENTS.md docs index for AI coding agents? (Y/n) Y
 
  ✓ created sus.json
  ✓ created .sus-docs/
  ✓ updated AGENTS.md with sus docs index
 
  📚 AGENTS.md docs index enabled. When you run sus add <package>,
     package documentation will be saved to .sus-docs/ and indexed in AGENTS.md.
 
  ✓ sus initialized successfully!

Behavior:

1. Prompts for configuration options (unless -y is used)
2. Creates sus.json with project settings
3. Creates .sus-docs/ directory (if docs index enabled)
4. Creates or updates AGENTS.md with sus docs index (if enabled)

sus add

Install packages with security checks before installation.

sus add <packages...>

Arguments:

• packages - One or more package specs (e.g., lodash, express@4.18.0, @types/node)

Flags:

Examples:

# Install a single package (JavaScript)
sus add express
 
# Install a specific version (JavaScript)
sus add lodash@4.17.21
 
# Install multiple packages (JavaScript)
sus add express cors helmet
 
# Install scoped packages (JavaScript)
sus add @types/node @prisma/client
 
# Install Python packages
sus add requests
sus add django==4.2.0
sus add flask sqlalchemy pytest
 
# Force install despite warnings (not recommended)
sus add sketchy-package --yolo
 
# Block on any warning
sus add untrusted-pkg --strict

Behavior:

1. Parses package specs and resolves versions
2. Queries the sus API for security assessment
3. Displays risk level with details (publisher, downloads, CVEs, threats)
4. For Clean packages: installs automatically
5. For Warning packages: prompts for confirmation (unless --strict)
6. For Critical packages: blocks installation (unless --yolo)
7. Installs via your detected package manager (npm/yarn/pnpm/bun for JavaScript, pip/poetry/pipenv/uv for Python)
8. Saves documentation to .sus-docs/ and updates AGENTS.md index

sus remove

Uninstall packages from your project.

sus remove <packages...>

Arguments:

• packages - One or more package names to remove

Examples:

# Remove a single package
sus remove lodash
 
# Remove multiple packages
sus remove express cors helmet

Behavior:

1. Detects your package manager
2. Runs the appropriate uninstall command
3. Removes documentation from .sus-docs/ and updates AGENTS.md index

sus scan

Audit all dependencies in your project for security issues.

sus scan

Flags:

Examples:

# Scan current project
sus scan
 
# Output as JSON (for CI/CD)
sus scan --json

Output:

$ sus scan
🔍 scanning 127 packages...
 
📦 lodash@4.17.20
   ⚠️  kinda sus
   └─ CVE-2021-23337: prototype pollution (medium)
 
📦 event-stream@3.3.6
   🚨 MEGA SUS
   └─ malware: flatmap-stream injection
 
───────────────────────────────
summary: 125 clean, 1 warning, 1 critical

Behavior:

1. Reads dependencies from package.json (JavaScript) or requirements.txt/pyproject.toml/Pipfile (Python)
2. Attempts to get exact versions from lockfiles
3. Performs bulk lookup via the sus API
4. Categorizes packages: clean, warnings, critical, unknown
5. Displays results sorted by severity
6. Exits with code 1 if critical issues are found (useful for CI)

sus check

Look up the security assessment for a package without installing it.

sus check <package>

Arguments:

• package - Package spec to check (e.g., lodash, express@4.18.0)

Examples:

# Check latest version
sus check axios
 
# Check specific version
sus check lodash@4.17.20

Output:

$ sus check axios
🔍 checking axios@1.6.0...
✅ not sus
   ├─ publisher: axios (verified)
   ├─ downloads: 45M/week
   ├─ cves: 0
   ├─ agentic threats: none
   ├─ install scripts: none
   └─ trust score: 92/100
 
📋 capabilities:
   ├─ 🌐 network: *
   └─ 🔑 env vars: HTTP_PROXY, HTTPS_PROXY

Behavior:

1. Parses package spec (name and optional version)
2. Fetches full assessment from the sus API
3. If not yet scanned, requests a scan and shows estimated time
4. Displays complete risk assessment including:
   • Risk level and trust score
   • Publisher information
   • CVEs with descriptions
   • Agentic threats (if any)
   • Install scripts
   • Capabilities (network, filesystem, process, environment, native)

sus update

Check for and update dependencies to their latest safe versions.

sus update

Flags:

Examples:

# Update all dependencies
sus update
 
# Preview updates without applying
sus update --dry-run

Output:

$ sus update --dry-run
📦 Available updates:
   ├─ express: 4.18.0 → 4.21.0 ✅
   ├─ lodash: 4.17.20 → 4.17.21 ✅
   └─ axios: 1.5.0 → 1.6.0 ✅
 
Run without --dry-run to apply updates.

Behavior:

1. Reads current dependencies from package.json (JavaScript) or requirements.txt/pyproject.toml/Pipfile (Python)
2. Checks latest version for each package via the sus API
3. Compares current vs latest versions
4. If --dry-run: shows available updates and stops
5. If not: updates each package using your package manager
6. Each update goes through the same security checks as sus add

sus why

Show why a package exists in your dependency tree.

sus why <package>

Arguments:

• package - Package name to trace

Examples:

# Find why lodash is installed
sus why lodash
 
# Trace a transitive dependency
sus why minimist

Output:

$ sus why minimist
minimist@1.2.8
├─ mkdirp@0.5.6
│  └─ your-project
└─ optimist@0.6.1
   └─ handlebars@4.7.7
      └─ your-project

Behavior:

1. Detects your package manager
2. Delegates to the underlying package manager's why command
3. Pretty-prints the dependency chain with highlighting

Global Options

These options work with all commands:

Environment Variables:

Risk Levels

sus categorizes packages into three risk levels:

Clean

No issues detected. Package installs automatically.

✅ not sus
   ├─ publisher: expressjs (verified)
   ├─ downloads: 32M/week
   └─ cves: 0

Warning

Minor issues found. sus prompts for confirmation before installing.

⚠️  kinda sus
   ├─ CVE-2021-23337: prototype pollution (medium)
   └─ trust score: 45/100

Use --strict to block warnings, or confirm to proceed.

Critical

Major security threats. Installation is blocked by default.

🚨 MEGA SUS
   ├─ malware: flatmap-stream injection
   ├─ targets: cryptocurrency wallets
   └─ status: COMPROMISED

Use --yolo to force install (not recommended).

Exit Codes