CLI Overview

The sus command-line interface for secure package installation

Introduction

The sus CLI is a drop-in addition to your existing package manager workflow. Instead of running npm install directly, you run sus add to get security scanning before installation.

The CLI:

• Scans packages before installation for CVEs, malware, and agentic threats
• Blocks dangerous packages by default
• Maintains an AGENTS.md docs index for AI coding tools
• Works with npm, yarn, pnpm, bun, pip, poetry, pipenv, and uv

How It Works

When you run a sus command, here's what happens:

1. Query API: sus checks the package against pre-scanned results in the cloud
2. Risk Assessment: Returns Clean, Warning, or Critical based on detected threats
3. Install Decision: Clean packages install automatically, warnings prompt, critical blocks
4. Package Manager: sus delegates to your detected package manager (npm, yarn, pnpm, bun, pip, poetry, pipenv, or uv)
5. Docs Index: Saves documentation to .sus-docs/ and updates AGENTS.md

Package Manager Detection

sus automatically detects which package manager to use based on lockfiles and configuration files in your project:

JavaScript/Node.js

Python

You don't need to configure anything. sus will use the right package manager automatically.

Example Output

Here's what you see when adding a safe package:

$ sus add express
🔍 checking express@4.21.0...
✅ not sus
   ├─ publisher: expressjs (verified)
   ├─ downloads: 32M/week
   ├─ cves: 0
   └─ install scripts: none
📦 installed
📝 updated AGENTS.md docs index

And when sus blocks a dangerous package:

$ sus add event-stream@3.3.6
🔍 checking event-stream@3.3.6...
🚨 MEGA SUS
   ├─ malware: flatmap-stream injection
   ├─ targets: cryptocurrency wallets
   └─ status: COMPROMISED
❌ not installed. use --yolo to force (don't)

Next Steps

• Installation - How to install the sus CLI
• Commands - Full command reference with all options