Upshift User Guide

Getting started, core workflow, and features. See the docs index for all documentation.

Use the tools: Install the CLI (npm install -g upshift-cli), run upshift scan in a project, and try Radar (paste reports—no account). For dashboard and Pro, Sign in. Details: Access & auth.

Quick start (5 minutes)

  1. Install: npm install -g upshift-cli
  2. Scan: In your project, run upshift scan to see outdated deps and vulnerabilities.
  3. Explain: Pick a package and run upshift explain <pkg> --risk (or --ai for AI analysis, 1 credit).
  4. Upgrade: Run upshift upgrade <pkg> — Upshift runs your tests and rolls back if they fail.
  5. Batch (optional): Run upshift upgrade --all-minor for safe minor/patch upgrades.

Works with Node (npm, yarn, pnpm), Python (pip/poetry), Ruby (bundler), and Go (go.mod). Use upshift radar to open the central dashboard.

Getting started

  1. Install: npm install -g upshift-cli
  2. Run in a project: cd your-project && upshift scan
  3. Explain a package: upshift explain react --risk or upshift explain react --ai (AI costs 1 credit)
  4. Upgrade: upshift upgrade react (runs tests, rolls back on failure)

See CLI reference for all commands and options.

Core workflow

Scan → Explain → Upgrade → Fix (if needed)

1. Scan

See what's outdated and vulnerable:

upshift scan
upshift scan --json
upshift scan --licenses
upshift scan --report report.json   # for Radar

2. Explain

Understand breaking changes before upgrading:

upshift explain <package>
upshift explain <package> --risk
upshift explain <package> --changelog
upshift explain <package> --ai    # AI analysis (1 credit)

Output includes "Used in your code" (import/require scan) and risk (low/medium/high).

3. Upgrade

upshift upgrade <package>
upshift upgrade <package> --to 19.0.0
upshift upgrade <package> --dry-run
upshift upgrade --all
upshift upgrade --all-minor
upshift upgrade --all --dry-run

4. Fix

If code breaks, get AI-suggested code changes:

upshift fix <package>
upshift fix <package> --dry-run

5. Rollback

upshift rollback

Suggest and plan

Suggest — Recommended upgrades (low risk, high value):

upshift suggest
upshift suggest --limit 10 --json

Plan — Ordered upgrade plan (dependency order + risk):

upshift plan
upshift plan --mode minor --json

Migration templates

Apply curated migration steps (e.g. React 18→19, Vue 2→3):

upshift migrate <package> --list
upshift migrate react --dry-run
upshift migrate react
upshift migrate next --template next-13-to-14

Radar (central view)

See dependency health across all your repos:

  1. In each repo: upshift scan --report report.json
  2. Open upshiftai.dev/radar or run upshift radar
  3. Paste or upload the JSON; view summary (repos, outdated, vulns)

Radar Pro (Pro/Team): persisted dashboard, history, alerts. See Radar.

Configuration

Create .upshiftrc.json with upshift init. Key options:

  • Approval (HITL) — approval.mode: prompt (default), none, or webhook; approval.requireFor: ["major"] or ["all"].
  • Upgrade policy — upgradePolicy: { blockRisk: ["high"] } blocks high-risk upgrades; use -y to override.
  • Auto — autoConfirm: true skips prompts; autoTest: true runs tests after upgrade.

Full reference: Configuration.

Python, Ruby, Go

  • Scan — In a Python/Ruby/Go project, upshift scan detects the ecosystem and runs the right scanner.
  • Explain / Upgrade (Python) — Full parity: version delta, --ai, upgrade with backup, test, rollback.
  • Explain / Upgrade (Ruby/Go) — Same: explain with risk/changelog, upgrade with tests and rollback.

VS Code

  • Explain for current file — Right-click in a .ts/.tsx/.js/.jsx file → "Upshift: Explain dependency for current file".
  • Fix for current file — Right-click → "Upshift: Fix dependency for current file" (dry-run in channel; apply in editor or terminal).
  • Command palette: "Upshift: Explain Package", "Upshift: Upgrade Package", etc.

CI/CD

Use -y to skip prompts, or set approval.mode: "none". For webhook approval, set approval.webhookUrl. Set UPSHIFT_RECORD_OUTCOMES=1 to append upgrade outcomes to .upshift/outcomes.json (local only).

When it breaks and guardrails

Tests are the guardrail; we roll back on failure. Review LLM-generated fixes (e.g. upshift fix --dry-run). See When it breaks & guardrails and Opt-in insights.

For risk checks and a testing checklist, see What to anticipate and test.

Credits and billing

  • Explain --ai costs 1 credit; fix costs 3 credits. You get 10 free credits by default.
  • upshift credits — check balance; upshift buy-credits / upshift subscribe for more.

Pricing · Docs index