Commands

Complete reference for all brin CLI commands

brin init

Initialize brin in your project. Sets up the AGENTS.md docs index and adds package installation instructions for AI agents.

brin init

Flags:

Examples:

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

Output:

$ brin init
 
  🔧 initializing brin...
 
  Enable AGENTS.md docs index for AI coding agents? (Y/n) Y
 
  ✓ created brin.json
  ✓ created .brin-docs/
  ✓ updated AGENTS.md with brin docs index
  ✓ added package installation instructions to AGENTS.md
 
  ✓ brin initialized successfully!

Behavior:

1. Prompts for configuration options (unless -y is used)
2. Creates brin.json with project settings
3. Creates .brin-docs/ directory (if docs index enabled)
4. Creates or updates AGENTS.md with brin docs index (if enabled)
5. Adds package installation instructions to AGENTS.md so AI agents use brin add instead of direct package manager commands

brin add

Install packages with security checks before installation.

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

Behavior:

1. Parses package specs and resolves versions
2. Queries the brin 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 .brin-docs/ and updates AGENTS.md index

brin remove

Uninstall packages from your project.

brin remove <packages...>

Arguments:

• packages - One or more package names to remove

Examples:

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

Behavior:

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

brin uninstall

Remove brin from your system. This command is for curl-based installations.

brin uninstall

Flags:

Examples:

# Uninstall with confirmation prompt
brin uninstall
 
# Skip confirmation
brin uninstall --yes
 
# Also remove project files
brin uninstall --all

Output:

$ brin uninstall
 
  ⚠️  This will remove brin from your system.
 
  Are you sure? (y/N) y
 
  ✓ removed brin binary
  ✓ brin has been uninstalled
 
  To reinstall, run:
  curl -fsSL https://brin.sh/install.sh | sh

Behavior:

1. Prompts for confirmation (unless --yes is used)
2. Removes the brin binary from your system
3. If --all is specified, also removes:
   • .brin-docs/ directory
   • brin.json configuration file
   • Sus Docs Index section from AGENTS.md (preserves other content)
4. Shows reinstall instructions after successful removal

brin upgrade

Check for and install the latest version of brin from GitHub releases. This command is for curl-based installations.

brin upgrade

Flags:

Examples:

# Upgrade if newer version available
brin upgrade
 
# Re-download even if on latest
brin upgrade --force

Output:

$ brin upgrade
 
  🔍 checking for updates...
  ✓ new version available: v0.1.6
 
  📦 downloading brin v0.1.6...
  ✓ brin upgraded to v0.1.6
 
$ brin upgrade
 
  🔍 checking for updates...
  ✓ already on latest version (v0.1.6)

Behavior:

1. Fetches latest release information from GitHub
2. Compares current version with latest available
3. If newer version exists (or --force is used):
   • Downloads the latest binary for your platform
   • Replaces the existing brin binary
4. If already on latest and no --force: exits with success message

brin scan

Audit all dependencies in your project for security issues.

brin scan

Flags:

Examples:

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

Output:

$ brin 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 brin 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)

brin check

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

brin check <package>

Arguments:

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

Examples:

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

Output:

$ brin 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 brin 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)

brin update

Check for and update dependencies to their latest safe versions.

brin update

Flags:

Examples:

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

Output:

$ brin 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 brin 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 brin add

brin why

Show why a package exists in your dependency tree.

brin why <package>

Arguments:

• package - Package name to trace

Examples:

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

Output:

$ brin 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

brin skills check

Check a skill's security posture without installing it. Scans the SKILL.md from a GitHub repository for threats and chain-loading patterns.

brin skills check <skill>

Arguments:

• skill - A skill identifier in one of two forms:
  • owner/repo — Check all skills in a repository (e.g. anthropic/skills)
  • owner/repo/skill-name — Check a specific skill (e.g. anthropic/skills/mcp-builder)

Examples:

# Check all skills in a repository
brin skills check owner/repo
 
# Check a specific skill
brin skills check owner/repo/skill-name

Output:

$ brin skills check acme/tools/code-review
🔍 checking skill acme/tools/code-review...
 
📋 acme/tools/code-review
   ├─ repo: github.com/acme/tools
   ├─ trust score: 87/100
   ├─ chain-loading: none detected
   └─ threats: none
 
✅ skill looks clean
 
$ brin skills check risky-org/agent-helpers/setup
🔍 checking skill risky-org/agent-helpers/setup...
 
📋 risky-org/agent-helpers/setup
   ├─ repo: github.com/risky-org/agent-helpers
   ├─ trust score: 34/100
   ├─ chain-loading: ⚠️  2 references detected
   │  ├─ installs npm package: unknown-pkg
   │  └─ loads skill: other-org/repo/helper
   └─ threats:
      └─ ⚠️  patterns consistent with data exfiltration (confidence: 0.78)
 
⚠️  skill flagged for review

Behavior:

1. Resolves the skill identifier to a GitHub repository and locates the SKILL.md file(s)
2. Fetches the skill content via the SkillsAdapter (GitHub-hosted skills registry)
3. Runs threat detection — initial scan uses minimax-m2p5 for speed, with Opus verification for flagged threats
4. Checks for chain-loading patterns — instructions that tell agents to install other skills or packages
5. Displays a tailored output showing repo, trust score, and threats (instead of the CVE/download-focused output used for npm/PyPI packages)
6. Opus-verified threats are marked as Verified and affect the overall risk level; unverified threats are shown as indicators for manual review

brin skills add

Install a skill after running safety checks. Works like brin add but for Agent Skills instead of packages.

brin skills add <skill>

Arguments:

• skill - A skill identifier: owner/repo/skill-name (e.g. anthropic/skills/mcp-builder)

Flags:

Examples:

# Install a skill with security checks
brin skills add owner/repo/skill-name
 
# Skip all safety checks (not recommended)
brin skills add owner/repo/skill-name --yolo
 
# Block on any warning
brin skills add owner/repo/skill-name --strict

Output:

$ brin skills add acme/tools/code-review
🔍 checking skill acme/tools/code-review...
 
📋 acme/tools/code-review
   ├─ repo: github.com/acme/tools
   ├─ trust score: 87/100
   ├─ chain-loading: none detected
   └─ threats: none
 
✅ skill looks clean
📦 installing skill...
✓ skill installed successfully

Behavior:

1. Runs the same security assessment as brin skills check
2. For Clean skills: installs automatically
3. For Warning skills: prompts for confirmation (unless --strict, which blocks)
4. For Critical skills: blocks installation (unless --yolo)
5. Installs the skill into your project

Skill Identifier Format

Skills use the format owner/repo or owner/repo/path to reference GitHub-hosted Agent Skills (SKILL.md files).

Examples:

• anthropic/skills/mcp-builder — the mcp-builder skill in github.com/anthropic/skills
• acme/tools — all skills in github.com/acme/tools

Chain-Loading Detection:

Chain-loading is when a skill instructs an AI agent to install additional skills or packages. This is a supply-chain risk unique to the agent ecosystem because:

• A seemingly harmless skill can pull in assessed-as-high-risk dependencies
• Nested skill references can create deep trust chains that are difficult to audit manually
• Package installations triggered by skills bypass the normal brin add security checks

Both skills check and skills add automatically detect and report chain-loading patterns. Nested skills referenced by chain-loading are automatically queued for scanning.

Global Options

These options work with all commands:

Environment Variables:

Exit Codes