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. (Needs a test script; without one there is no rollback gate and the CLI says so.)
  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.

When you already have Renovate or Dependabot

Keep your existing PR automation; it excels at opening version bumps. Upshift is the next step when a bump lands (or before you merge): explain breaking changes, optionally fix with review (fix --dry-run first), upgrade locally with tests + rollback, and use Radar for fleet visibility. You do not have to pick one tool.

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

  • Scan: Status bar or “Upshift: Scan Dependencies”.
  • 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.

Roadmap (package.json acquisition): The plan is in-editor cues when you open package.json (for example, surfacing 1–2 critical vulnerabilities with a Fix with Upshift entry point) so “notice problem → act” is one step. Tracked in repo BACKLOG.md; today use the commands above.

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; Upshift rolls 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.
  • Local LLM: If OPENAI_BASE_URL points at a non–OpenAI host, credits still apply unless you set UPSHIFT_SKIP_CREDITS_FOR_LOCAL_LLM=1.

Pricing · Docs index