SUS
sus
get started

Quickstart

Get up and running with sus in just a few minutes

Installation

Install sus using the install script:

Bash
curl -fsSL https://sus-pm.com/install.sh | sh

Initialize Your Project

Run sus init to set up sus in your project:

Bash
sus init
Bash
  🔧 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
 
  ✓ sus initialized successfully!

This creates:

  • sus.json - Project configuration
  • AGENTS.md - Instructions and docs index for AI agents

Use -y to skip prompts: sus init -y

Add Your First Package

Instead of using npm install, use sus add to install packages with safety checks:

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

If a package is suspicious, sus will warn you:

Bash
sus add event-stream@3.3.6
Bash
🔍 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)

Scan an Existing Project

Audit all dependencies in your current project:

Bash
sus scan
Bash
🔍 scanning 847 packages...
 
📦 lodash@4.17.20
   ⚠️  kinda sus — CVE-2021-23337 (prototype pollution)
   └─ fix: sus update lodash
 
📦 node-ipc@10.1.0
   🚨 MEGA SUS — known sabotage (march 2022)
   └─ fix: sus remove node-ipc
 
───────────────────────────────────
summary: 845 clean, 1 warning, 1 critical

Check a Package

Look up a package without installing it:

Bash
sus check lodash
Bash
📦 lodash
 
fetching security assessment...
✓ assessment found
 
✅ not sus
   ├─ publisher: lodash (verified)
   ├─ downloads: 45M/week
   ├─ cves: 0
   └─ install scripts: none

Package Manager Auto-Detection

sus automatically detects your package manager based on lock files:

  • pnpm-lock.yaml → pnpm
  • yarn.lock → yarn
  • bun.lock → bun
  • package-lock.json → npm (default)

No configuration needed—just run sus add and it works.

AGENTS.md Docs Index

When you install a package with sus add, it automatically:

  1. Saves package documentation to .sus-docs/
  2. Updates the docs index in AGENTS.md

This gives AI coding agents instant access to package documentation without requiring them to search for it. Based on Vercel's research, this passive context approach achieves 100% pass rate compared to 79% for active skill retrieval.

Learn more in the AGENTS.md documentation.

Common Flags

Bash
sus add express --strict    # Block on any warning
sus add express --yolo      # Skip checks (not recommended)
sus scan --json             # Machine-readable output

Other Commands

Bash
sus init               # Initialize sus in your project
sus remove <package>   # Uninstall a package
sus update             # Update dependencies and re-scan
sus why <package>      # Show why a package is in your tree

Next Steps