CLI Reference

Quick reference for all Upshift commands and options. Run upshift --help or upshift <command> --help for the latest.

Global

upshift [options] [command]
  -V, --version   output version
  -h, --help      display help

Core

scan

Scan dependencies for updates and vulnerabilities.

upshift scan [options]
  --json           Output as JSON
  --licenses       Include license per direct dependency (npm, Python)
  --report <path>  Write JSON report to file (for Radar)
  --cwd <path>     Project directory (default: .)

Supports Node (npm/yarn/pnpm), Python (pip/poetry), Ruby (bundler), Go (go.mod). Auto-detects ecosystem.

explain

Explain breaking changes for a dependency.

upshift explain <package> [options]
  --json       Output as JSON
  --risk       Show risk (low/medium/high)
  --changelog  Fetch changelog from GitHub
  --ai         AI analysis (1 credit)
  --from <v>   Current version
  --to <v>     Target version
  --cwd <path>

fix

AI-powered code fixes for breaking changes (3 credits).

upshift fix <package> [options]
  --dry-run   Preview changes without applying
  --cwd <path>

upgrade

Upgrade a dependency (single or batch). Runs tests; rolls back on failure.

upshift upgrade [package] [options]
  --to <version>   Target version (default: latest)
  --all            Upgrade all outdated
  --all-minor      Only minor/patch
  --all-patch      Only patch
  --dry-run        Show planned changes, no file changes
  -y, --yes        Skip confirmation prompts
  --skip-tests     Skip tests after upgrade
  --cwd <path>

rollback

upshift rollback [options]
  --list   List available backups
  --cwd <path>

audit

Security audit with optional AI-powered remediation.

upshift audit [options]
  --ai       AI remediation suggestions (2 credits)
  --cwd <path>

Analysis

suggest

AI-ranked upgrade suggestions enriched with community confidence scores.

upshift suggest [options]
  --json       Output as JSON
  --limit <n>  Max suggestions (default: 5)
  --cwd <path>

plan

Multi-step upgrade plan ordered by dependency graph and risk.

upshift plan [options]
  --json        Output as JSON
  --mode <m>    all | minor | patch (default: all)
  --cwd <path>

debt

Calculate total upgrade debt in engineer-hours and estimated cost. Effort: patch=0.25h, minor=1h, major=8h (3h when a codemod exists).

upshift debt [options]
  --hourly-rate <n>   Engineer hourly rate (default: 150)
  --json              Output as JSON
  --cwd <path>

license

SPDX license compliance scan. Exits with code 1 on violations.

upshift license [options]
  --deny <licenses>    Comma-separated SPDX IDs to deny (e.g. GPL-3.0,AGPL-3.0)
  --allow <licenses>   Allowlist mode
  --copyleft           Flag all copyleft licenses as violations
  --json               Output as JSON
  --cwd <path>

compare

Side-by-side comparison of two versions: bundle size, downloads, dependencies, license, community confidence.

upshift compare <package> <versionA> <versionB> [options]
  --json       Output as JSON

Use latest as a version to resolve to the current latest.

changelog

Fetch release notes for a package from GitHub.

upshift changelog <package> [options]
  --limit <n>   Max releases (default: 5)
  --json        Output as JSON

sbom

Export a CycloneDX 1.4 software bill of materials.

upshift sbom [options]
  --output <path>  Write to file instead of stdout
  --json           Output raw JSON
  --cwd <path>

badge

Generate a README health badge (shields.io URL).

upshift badge [options]
  --style <s>    flat | flat-square | plastic (default: flat)
  --cwd <path>

Migrate

AST-aware major version migration with codemods.

upshift migrate <package> [options]
  --template <name>       Template id (e.g. react-18-19, next-13-14)
  --template-file <path>  Custom migration JSON
  --dry-run               Preview changes, no file writes
  --list                  List available templates for package
  --cwd <path>

Radar

Dependency health overview. --score computes an A–F grade (exits 1 when score < 40).

upshift radar [options]
  --score      Compute 0–100 health score and A–F grade
  --json       Output as JSON (useful for CI)
  --no-open    Print URL only, don't open browser
  --cwd <path>

Automation

schedule

Generate or install a GitHub Actions workflow for scheduled scans.

upshift schedule generate [options]
  --cron <expr>     Cron expression (default: weekly Monday 9am)
  --slack <url>     Add Slack notification step
  --discord <url>   Add Discord notification step
  --no-score        Skip health score step

upshift schedule install [options]
  --cron <expr>     Cron expression
  --slack <url>     Slack webhook URL
  --force           Overwrite existing workflow file

notify

upshift notify [options]
  --slack <url>     Slack incoming webhook
  --discord <url>   Discord webhook
  --webhook <url>   Custom webhook (POST JSON)
  --cwd <path>

pr-description

Generate a PR description for pending upgrades.

upshift pr-description [options]
  --title <title>    PR title override
  --clipboard        Copy to clipboard (pbcopy / xclip)
  --output <path>    Write to file
  --cwd <path>

release

Generate a CHANGELOG from git history using Conventional Commits.

upshift release [options]
  --version <v>    Version tag (default: from package.json)
  --output <path>  Prepend to CHANGELOG.md
  --json           Output as JSON

Interactive & monorepo

interactive

upshift interactive [options]
  --cwd <path>

workspaces

upshift workspaces [options]
  --score      Compute A–F health score per workspace
  --json       Output as JSON
  --cwd <path>

Setup & diagnostics

Environment variables

Options can be set in .upshiftrc.json; CLI flags always override config. See Configuration.