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.

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): We plan 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 for vibe coders. 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; 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.
  • 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