@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"
      }
    }
  }
}

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

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

1. 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 add a live dependency health badge to any repository. This badge shows the current state of your dependencies and updates automatically.

How it works

1. Generates a GitHub Actions workflow that runs weekly (or on push to main)
2. Executes rup doctor to analyze your dependencies
3. Publishes the results as a JSON file via GitHub Pages
4. Shields.io renders the JSON as a dynamic badge in your README

For any user/repository

This feature works for ANY repository, not just this one:

# In your project directory
rup badge init --owner <your-github-username> --repo <your-repo-name> --readme

This will:

• Create .github/workflows/health-badge.yml (runs weekly + on push)
• Generate .artifacts/badges/README-badge-snippet.md with your badge markdown
• Optionally update your README.md with the badge

Setup requirements

1. Enable GitHub Pages in your repository settings:

   • Go to Settings → Pages
   • Source: GitHub Actions (not "Deploy from branch")

2. Run the init command:

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

1. Commit and push the workflow file
2. The badge will update automatically on the schedule or when you push to main

Manual usage

Print only the badge URL:

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

Generate badge JSON manually (for CI):

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

Update frequency

The badge updates:

• Weekly (every Monday at 9 AM UTC) via cron schedule
• On every push to main/master branch
• Manually via workflow_dispatch in GitHub Actions UI

Example badge

The badge at the top of this README is generated using this same system.

License

MIT