@rainy-updates/cli

Rainy Updates is a deterministic dependency review and upgrade operator for Node monorepos and CI.

@rainy-updates/cli is built for teams that need fast dependency detection, trustworthy review, controlled upgrades, and automation-ready outputs for CI/CD.

Overview

Rainy Updates gives teams one dependency lifecycle:

1. check — detects candidate updates
2. doctor — summarizes the current situation
3. predict — estimates upgrade break risk before applying changes
4. review / dashboard — decides what should happen (interactive decision surface)
5. upgrade — applies the approved change set

Everything else supports that lifecycle: CI orchestration, advisory lookup, peer resolution, licenses, snapshots, baselines, and fix-PR automation.

For whom

• Node monorepo teams that want deterministic CI artifacts
• Engineers who want to review dependency risk locally before applying changes
• Teams that need fewer, better upgrade decisions instead of noisy automated PR churn

Why use it

• Detects updates quickly across single-package repos and workspaces
• Centralizes security, peer, license, health, and behavioral risk review
• Applies updates safely with configurable targets (patch, minor, major, latest)
• Enforces policy rules per package
• Supports offline and cache-warmed execution for deterministic CI runs
• Produces machine-readable artifacts: JSON, SARIF, GitHub outputs, and PR reports

Quick start

# 1) Detect what changed
bunx --bun @rainy-updates/cli check --workspace --show-impact

# 2) Summarize what matters
bunx --bun @rainy-updates/cli doctor --workspace

# 3) Decide in the dashboard
bunx --bun @rainy-updates/cli dashboard --mode review --plan-file .artifacts/decision-plan.json

# 4) Predict break risk
bunx --bun @rainy-updates/cli predict --workspace

# 5) Apply the approved plan
bunx --bun @rainy-updates/cli upgrade --from-plan .artifacts/decision-plan.json

Installation

Fast install (global)

Pick one:

bun add -g @rainy-updates/cli

npm i -g @rainy-updates/cli

pnpm add -g @rainy-updates/cli

Verify:

rup --version
rup mcp --help

Option 1: Bun runtime (recommended, no install needed)

bunx --bun @rainy-updates/cli check
bunx --bun @rainy-updates/cli audit --severity high
bunx --bun @rainy-updates/cli ci --workspace --mode strict

Option 2: Project dependency

npm install --save-dev @rainy-updates/cli
pnpm add -D @rainy-updates/cli
bun add -d @rainy-updates/cli

Then use via rup, rainy-up, or rainy-updates:

rup check
rainy-up doctor --workspace
rainy-updates upgrade --from-plan .artifacts/decision-plan.json

Option 3: Standalone binaries

Download pre-compiled binaries from GitHub Releases for:

• Linux x64 / arm64
• macOS x64 / arm64
• Windows x64

Each release includes:

• rup — human CLI
• rup-mcp — editor and agent integrations

Option 4: npx (compatibility)

npx @rainy-updates/cli check
npx @rainy-updates/cli audit --severity high

Note: Bun runtime is fastest. npm/npx are supported compatibility paths.

Commands

Core workflow

| Command | Purpose | |---------|---------| | check | Detect candidate dependency updates | | doctor | Summarize current dependency health | | review | Decide what to do with security, risk, peer, and policy context | | predict | Estimate break risk and confidence before applying | | dashboard | Interactive decision console (primary UI) | | upgrade | Apply the approved change set |

Security & health

| Command | Purpose | |---------|---------| | audit | Scan for CVEs using OSV.dev + GitHub Advisory Database | | health | Detect stale, deprecated, and unmaintained packages | | bisect | Binary-search to find which version broke your tests |

CI & automation

| Command | Purpose | |---------|---------| | ci | Run CI-focused dependency automation with policy gates | | warm-cache | Prefetch package metadata for fast offline checks | | baseline | Save and compare dependency baseline snapshots | | ga | Audit GA and CI readiness for current checkout |

Utilities

| Command | Purpose | |---------|---------| | explain | Summarize a package update with risk, changelog, and security context | | watch | Monitor dependency updates and advisories | | self-update | Check/apply Rainy CLI global updates | | mcp | Run local MCP server for AI agents | | init-ci | Generate GitHub Actions workflow | | reachability | Estimate advisory exploitability reachability | | exceptions | Manage VEX-like advisory exceptions | | supply-chain | Scan Docker, GitHub Actions, Terraform, and Helm supply-chain risks | | attest | Verify provenance/signing/SBOM posture with policy verdicts |

Usage examples

Detection & review

# Detect updates with impact analysis
rup check --format table
rup check --workspace --show-impact

# Summarize dependency health
rup doctor --workspace
rup doctor --verdict-only

# Review with risk context
rup review --security-only
rup review --risk high --diff major
rup dashboard --mode review --plan-file .artifacts/decision-plan.json

Security & health

# Scan for CVEs
rup audit
rup audit --severity high
rup audit --summary
rup audit --fix          # prints install command for detected package manager

# Check maintenance health
rup health
rup health --stale 6m   # flag packages with no release in 6 months
rup health --stale 180d # same but in days

# Find breaking version
rup bisect axios --cmd "bun test"
rup bisect react --range "18.0.0..19.0.0" --cmd "npm test"
rup bisect lodash --cmd "npm run test:unit" --dry-run

Upgrade & verification

# Apply approved plan with verification
rup upgrade --from-plan .artifacts/decision-plan.json
rup upgrade \
  --from-plan .artifacts/decision-plan.json \
  --verify install,test \
  --test-command "bun test" \
  --verification-report-file .artifacts/verification.json

# Explain a package update
rup explain react

CI & automation

# Warm cache for deterministic offline CI
rup warm-cache --workspace --concurrency 32
rup check --workspace --offline --ci

# Save and compare baseline drift
rup baseline --save --file .artifacts/deps-baseline.json --workspace
rup baseline --check --file .artifacts/deps-baseline.json --workspace --ci

# CI orchestration with policy gates
rup ci --workspace --mode strict --gate review --plan-file .artifacts/decision-plan.json --format github
rup ci --workspace --mode strict --gate upgrade --from-plan .artifacts/decision-plan.json --verify test --test-command "npm test"

# Batch fix branches by scope (enterprise)
rup ci --workspace --mode enterprise --group-by scope --fix-pr --fix-pr-batch-size 2

# Audit CI readiness
rup ga --workspace

# Generate GitHub Actions workflow
rup init-ci --mode enterprise --schedule weekly
rup init-ci --mode minimal --schedule daily
rup init-ci --target cron --mode strict --schedule daily
rup init-ci --target systemd --mode strict --schedule weekly
rup init-ci --mode strict --schedule weekly --with-badge

Monitoring

# Watch for updates and advisories
rup watch --workspace --severity high

# Reachability and exceptions
rup reachability --workspace --format summary
rup exceptions list --active-only

# Cross-stack supply-chain + attestation
rup supply-chain --scope all --format summary
rup attest --action verify --format table

Configuration

Policy file

Control upgrade behavior with .rainyupdates-policy.json:

{
  "ignore": ["@types/*", "eslint*"],
  "packageRules": {
    "react": { "maxTarget": "minor", "target": "patch", "autofix": false },
    "typescript": { "ignore": true }
  }
}

Use it with:

rup check --policy-file .rainyupdates-policy.json

Config file

Configuration can be loaded from:

• .rainyupdatesrc
• .rainyupdatesrc.json
• package.json field: rainyUpdates

Environment

• .env files are auto-loaded by Bun
• .npmrc is read for private package registries
• FORCE_COLOR=0 disables colored output (useful for CI)

AI Agents (MCP)

Rainy Updates runs as a local MCP server for Claude Desktop, Cursor, and other MCP-capable agents to inspect dependency health.

5-minute setup

1. Install globally (rup) using the commands above.

2. Add this MCP JSON entry:

{
  "mcpServers": {
    "rainy-updates": {
      "command": "rup",
      "args": ["mcp"],
      "env": {
        "FORCE_COLOR": "0",
        "RUP_DEFAULT_CWD": "/Users/<you>/your-repo"
      }
    }
  }
}

3. If your client doesn't inherit PATH, use absolute binary path:

{
  "mcpServers": {
    "rainy-updates": {
      "command": "/Users/<you>/.bun/bin/rup",
      "args": ["mcp"]
    }
  }
}

4. Start asking:

• Run rup_context and confirm the effective cwd
• Run rup_doctor for this workspace
• Show high-risk updates with rup_review
• Check critical CVEs with rup_audit

Generate config JSON automatically:

rup mcp --print-config --client claude
rup mcp --print-config --client cursor
rup mcp --print-config --client generic

More client examples

Cursor example:

{
  "mcpServers": {
    "rainy-updates": {
      "command": "rup",
      "args": ["mcp"]
    }
  }
}

If your MCP client does not send cwd per tool call, you can also define a persistent default path in config:

{
  "mcp": {
    "cwd": "/Users/<you>/your-repo"
  }
}

Transport options

• Default: stdio via rup-mcp
• HTTP: rup-mcp --transport http --port 3741 --http-path /mcp
• Auth: rup-mcp --transport http --port 3741 --auth-token local-dev-token
• Reliability controls: --max-inflight 4 --max-queue 64 --tool-timeout-ms 30000 --initialize-timeout-ms 10000
• Diagnostics: --diag-json emits structured MCP diagnostics to stderr

MCP engine mode

Rainy includes a phased SDK migration path:

• RAINY_MCP_ENGINE=legacy (default): current production MCP engine
• RAINY_MCP_ENGINE=sdk: official @modelcontextprotocol/sdk engine path
• RAINY_MCP_ENGINE_FALLBACK=0: disable automatic fallback when sdk engine fails

Docs: MCP quickstart · Compatibility guide · Agent playbook · MCP overview · Tools reference · Claude Desktop · Cursor · Security model

Documentation

• Command model — Check → Doctor → Review → Upgrade
• MCP quickstart — Copy-paste setup for MCP clients
• MCP compatibility — Multi-client and multi-environment setup
• Agent playbook — Best practices for agent workflows
• Review workflow — Decision-making guide
• TUI guide — Dashboard usage
• Risk engine — Risk assessment methodology
• Benchmarks — Performance methodology
• Comparison — vs Dependabot & Renovate
• Badges — Health badge setup for any repository
• Supply-chain & attest — Cross-stack scanner + provenance policy checks
• Roadmap — Long-term vision

Health badge

Use rup badge to standardize a publishable quality badge for any repository.

1. Scaffold workflow + README snippet:

rup badge init --owner <github-owner> --repo <repo-name> --readme

2. Print only the final URL/snippet:

rup badge url --owner <github-owner> --repo <repo-name>

3. Use the generated universal snippet:

cat .artifacts/badges/README-badge-snippet.md

Manual badge format:

![Repo Health](https://img.shields.io/endpoint?url=https://ferxalbs.github.io/rainy-updates/badges/health.json)

Raw badge JSON generation (inside CI):

rup doctor --badge-file .public/badges/health.json

The workflow .github/workflows/health-badge.yml publishes this file via GitHub Pages.

License

MIT