@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.

Comparison: Why Rainy vs Dependabot and Renovate

Command model: Check → Doctor → Review → Upgrade

Review workflow: Review workflow guide

TUI usage: TUI guide

Risk engine: Risk engine guide

Benchmarks: Benchmark methodology

What it is

Rainy Updates gives teams one dependency lifecycle:

• check detects candidate updates.
• doctor summarizes the current situation.
• review decides what should happen.
• dashboard is the primary interactive decision surface.
• upgrade applies the approved change set.

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

Who it is for

• 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.

60-second workflow

# 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) Apply the approved plan
bunx --bun @rainy-updates/cli upgrade --from-plan .artifacts/decision-plan.json

Why teams 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.

Install

# Preferred: run with Bun's runtime directly
bunx --bun @rainy-updates/cli check

# As a project dev dependency (recommended for teams)
npm install --save-dev @rainy-updates/cli
# or
pnpm add -D @rainy-updates/cli
# or
bun add -d @rainy-updates/cli

Once installed, three binary aliases are available in your node_modules/.bin/:

| Alias | Use case | | --------------- | ------------------------------------------- | | rup | Power-user shortcut — rup ci, rup audit | | rainy-up | Human-friendly — rainy-up check | | rainy-updates | Backwards-compatible (safe in CI scripts) |

# All three are identical — use whichever you prefer:
rup check
rainy-up check
rainy-updates check

Bun-first runtime

# Preferred no-install path:
bunx --bun @rainy-updates/cli check
bunx --bun @rainy-updates/cli audit --severity high
bunx --bun @rainy-updates/cli ci --workspace --mode strict

One-off usage with npx (compatibility path)

# Compatibility path when Bun is not available:
npx @rainy-updates/cli check
npx @rainy-updates/cli audit --severity high
npx @rainy-updates/cli ci --workspace --mode strict

Note: Rainy is Bun-first at runtime. bunx --bun @rainy-updates/cli ... is the fastest no-install path. The npm package and npx remain supported compatibility paths.

Commands

Primary workflow

• check — detect candidate dependency updates
• doctor — summarize the current dependency situation
• review — decide what to do with security, risk, peer, and policy context
• dashboard — open the primary interactive decision console
• upgrade — apply the approved change set
• ga — audit GA and CI readiness for the current checkout

Supporting workflow

• ci — run CI-focused dependency automation (warm cache, check/upgrade, policy gates)
• warm-cache — prefetch package metadata for fast and offline checks
• baseline — save and compare dependency baseline snapshots

Security & health (new in v0.5.1)

• audit — scan dependencies for CVEs using OSV.dev plus GitHub Advisory Database, with lockfile-aware version inference
• health — detect stale, deprecated, and unmaintained packages before they become liabilities
• bisect — binary-search across semver versions to find the exact version that broke your tests

Quick usage

Commands work with bunx --bun, with npx as a compatibility path, or with the rup / rainy-up shortcut if the package is installed.

# 1) Detect updates
bunx --bun @rainy-updates/cli check --format table
npx @rainy-updates/cli check --format table
rup check --format table                      # if installed

# 2) Summarize the state
bunx --bun @rainy-updates/cli doctor --workspace
rup doctor --workspace

# 3) Review and decide
bunx --bun @rainy-updates/cli review --security-only
rup dashboard --mode review --plan-file .artifacts/decision-plan.json
rup review --show-changelog

# 4) Apply an approved decision plan with verification
bunx --bun @rainy-updates/cli upgrade --from-plan .artifacts/decision-plan.json --verify install,test --test-command "bun test"
rup upgrade --from-plan .artifacts/decision-plan.json --verify install,test --test-command "npm test"

# 5) CI orchestration with policy gates
bunx --bun @rainy-updates/cli ci --workspace --mode strict --gate review --plan-file .artifacts/decision-plan.json --format github
rup ci --workspace --mode strict --gate review --plan-file .artifacts/decision-plan.json --format github

# 6) Replay an approved plan in CI
rup ci --workspace --mode strict --gate upgrade --from-plan .artifacts/decision-plan.json --verify test --test-command "npm test"

# 7) Batch fix branches by scope (enterprise)
npx @rainy-updates/cli ci --workspace --mode enterprise --group-by scope --fix-pr --fix-pr-batch-size 2
rup ci --workspace --mode enterprise --group-by scope --fix-pr --fix-pr-batch-size 2

# 8) Warm cache -> deterministic offline CI check
npx @rainy-updates/cli warm-cache --workspace --concurrency 32
npx @rainy-updates/cli check --workspace --offline --ci

# 9) Save and compare baseline drift
npx @rainy-updates/cli baseline --save --file .artifacts/deps-baseline.json --workspace
npx @rainy-updates/cli baseline --check --file .artifacts/deps-baseline.json --workspace --ci

# 10) Scan for known CVEs
npx @rainy-updates/cli audit
npx @rainy-updates/cli audit --severity high
npx @rainy-updates/cli audit --summary
npx @rainy-updates/cli audit --source osv
npx @rainy-updates/cli audit --fix          # prints the patching install command for the detected package manager
rup audit --severity high                   # if installed

`audit` resolves installed versions from lockfiles across npm, pnpm, and simple `bun.lock` workspace entries when available. It reports source-health warnings when OSV or GitHub returns only partial coverage.

# 11) Check dependency maintenance health
npx @rainy-updates/cli health
npx @rainy-updates/cli health --stale 6m   # flag packages with no release in 6 months
npx @rainy-updates/cli health --stale 180d # same but in days
rup health --stale 6m                       # if installed

# 12) Find which version introduced a breaking change
npx @rainy-updates/cli bisect axios --cmd "bun test"
npx @rainy-updates/cli bisect react --range "18.0.0..19.0.0" --cmd "npm test"
npx @rainy-updates/cli bisect lodash --cmd "npm run test:unit" --dry-run
rup bisect axios --cmd "bun test"           # if installed

# 13) Focus review on high-risk changes
rup review --risk high --diff major

# 14) Audit GA / CI readiness
rup ga --workspace

Decision Plans And Verification

Rainy can persist an approved update set as a deterministic decision plan and replay it later:

# Create a reviewed plan
rup dashboard --mode review --plan-file .artifacts/decision-plan.json

# Apply only that approved plan later
rup upgrade --from-plan .artifacts/decision-plan.json

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

This is the intended local review -> CI replay workflow.

Verification follows the target repository's package manager when one is detected. That means Bun repositories can verify with bun install / bun test, while npm and pnpm projects keep their native install/test flows.

CI Gates

ci supports explicit execution gates:

• --gate check runs detection only.
• --gate doctor computes the high-level verdict and doctor metadata.
• --gate review emits a decision plan artifact without mutating the repo.
• --gate upgrade replays an existing plan and can run verification.

What it does in production

Update detection engine

• Scans dependency groups: dependencies, devDependencies, optionalDependencies, peerDependencies.
• Resolves versions per unique package to reduce duplicate network requests.
• Uses network concurrency controls and resilient retries.
• Supports explicit registry retry/timeout tuning (--registry-retries, --registry-timeout-ms).
• Supports stale-cache fallback when registry calls fail.
• Supports streamed progress output for long CI runs (--stream).
• Exposes impact/risk metadata and homepage context in update output (--show-impact, --show-homepage).

Workspace support

• Detects package workspaces from:
  • package.json workspaces
  • pnpm-workspace.yaml
• Handles multi-manifest upgrade flows.
• Graph-aware sync mode (--sync) avoids breaking workspace:* references.

Policy-aware control

• Apply global ignore patterns.
• Apply package-specific rules.
• Enforce max upgrade target per package (for safer rollout).
• Support per-package target override and fix-pr inclusion (target, autofix).

Example policy file:

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

Use it with:

npx @rainy-updates/cli check --policy-file .rainyupdates-policy.json

Output and reporting

Human output

• --format table
• --format minimal

Review-centered outputs:

• check is optimized for detection.
• doctor is optimized for summary.
• review is optimized for decision-making.
• upgrade is optimized for safe application.

Automation output

• --format json
• --json-file <path>
• --sarif-file <path>
• --github-output <path>
• --pr-report-file <path>

These outputs are designed for CI pipelines, security tooling, and PR review automation.

Automatic CI bootstrap

Generate a workflow in the target project automatically:

# enterprise mode (recommended)
rup init-ci --mode enterprise --schedule weekly

# lightweight mode
rup init-ci --mode minimal --schedule daily

Generated file:

• .github/workflows/rainy-updates.yml

Modes:

• strict: warm-cache + review gate + artifacts + SARIF upload.
• enterprise: strict checks + runtime matrix + review/upgrade gates + retention policy.
• minimal: fast check-only workflow for quick adoption.

Schedule:

• weekly, daily, or off (manual dispatch only).

Command options

Global

• --cwd <path>
• --workspace
• --target patch|minor|major|latest
• --filter <pattern>
• --reject <pattern>
• --dep-kinds deps,dev,optional,peer
• --concurrency <n>
• --cache-ttl <seconds>
• --registry-timeout-ms <n>
• --registry-retries <n>
• --offline
• --stream
• --fail-on none|patch|minor|major|any
• --max-updates <n>
• --group-by none|name|scope|kind|risk
• --group-max <n>
• --cooldown-days <n>
• --pr-limit <n>
• --only-changed
• --interactive
• --plan-file <path>
• --from-plan <path>
• --verify none|install|test|install,test
• --test-command <cmd>
• --verification-report-file <path>
• --show-impact
• --show-homepage
• --mode minimal|strict|enterprise (for ci)
• --gate check|doctor|review|upgrade (for ci)
• --fix-pr-batch-size <n> (for batched fix branches in ci)
• --policy-file <path>
• --format table|json|minimal|github
• --json-file <path>
• --github-output <path>
• --sarif-file <path>
• --pr-report-file <path>
• --fix-pr
• --fix-branch <name>
• --fix-commit-message <text>
• --fix-dry-run
• --lockfile-mode preserve|update|error
• --no-pr-report
• --ci

Upgrade-only

• --install
• --pm auto|bun|npm|pnpm|yarn
• --sync

Review-only

• --security-only
• --risk critical|high|medium|low
• --diff patch|minor|major|latest
• --apply-selected

Doctor-only

• --verdict-only

Baseline-only

• --save
• --check
• --file <path>

Config support

Configuration can be loaded from:

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

CLI help

rup --help
rup <command> --help
rup --version

# or with the full name:
rainy-updates --help
npx @rainy-updates/cli --help

Reliability characteristics

• Node.js 20+ runtime.
• Works with npm and pnpm workflows.
• Uses optional undici pool path for high-throughput HTTP.
• Reads .npmrc default and scoped registries for private package environments.
• Cache-first architecture for speed and resilience.

CI/CD included

This package ships with production CI/CD pipelines in the repository:

• Continuous integration pipeline for typecheck, tests, build, and production smoke checks.
• Performance smoke gate (perf:smoke) to catch startup/runtime regressions in CI.
• Tag-driven release pipeline for npm publishing with provenance.
• Release preflight validation for npm auth/scope checks before publishing.

Product roadmap

The long-term roadmap is maintained in ROADMAP.md.

License

MIT