Quick Start Guide

This guide will help you get started with npq quickly.

Installation

Global Installation

npm install -g npq

Or via Homebrew:

brew install npq

Basic Usage

Install a Package with Audit

# Audit and install a package
npq install express

npq will:

1. Run all security checks on the package
2. Display warnings and errors grouped by category
3. Prompt for confirmation (or auto-continue after 15 seconds if only warnings)
4. Install the package if you confirm

Dry Run (Audit Only)

# Audit without installing
npq install express --dry-run

This runs all security checks but doesn't install the package. Useful for:

• Checking packages before adding to package.json
• CI/CD pipelines
• Auditing existing dependencies

Plain Text Output

# Plain text output (no colors/formatting)
npq install express --plain

Useful for:

• Logging to files
• CI/CD environments
• Non-interactive terminals

First Steps

1. Install npq globally:

   npm install -g npq

2. Try auditing a package:

   npq install express --dry-run

3. Review the output:

   • Errors (✖) block installation by default
   • Warnings (⚠) allow installation with confirmation
   • Summary shows counts of errors and warnings

4. Install if audit passes:

   npq install express

Integration with Package Managers

Automatic Auditing with Aliases

Create an alias to automatically audit all package installations:

# For npm - add to ~/.bashrc or ~/.zshrc
alias npm='npq-hero'

# For yarn
alias yarn="NPQ_PKG_MGR=yarn npq-hero"

# For pnpm
alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"

Now all npm install commands are automatically audited before installation.

Command-Line Options

Usage: npq install <package> [options]

Commands:
  install [package...]  Install one or more packages after auditing

Options:
  --dry-run               Run checks only, don't install
  --plain                 Force non-rich text output
  --packageManager        Package manager to use (default: npm)
  --pkgMgr                Alias for packageManager
  --disable-auto-continue Disable auto-continue countdown, always prompt
  -h, --help              Show help
  -v, --version           Show version

Common Use Cases

Install Multiple Packages

npq install express lodash axios

Install with Version Spec

npq install express@4.18.2
npq install lodash@^4.17.21

Use Different Package Manager

npq install express --packageManager=yarn

Or via environment variable:

NPQ_PKG_MGR=yarn npq install express

Disable Auto-Continue

npq install express --disable-auto-continue

This always prompts for explicit confirmation, even when only warnings are detected.

Next Steps

• See Integration Guide for workflow integration
• See Real-World Scenarios for common patterns
• See Reference: Configuration for environment variables
• See Reference: Security Marshalls for detailed security check documentation