Guides

Choosing a way in

The web tool, the REST API, the MCP server and the script use the same parameters and give the same plan. Pick the one that is nearest to where you already work.

You want to	Use
look at a plan once	the web tool
apply a plan in a terminal or a CI step	the script
call it from your own code	the REST API
let an assistant read the explanations	the MCP server

Apply a plan

Ripedeps never writes to your files. The script prints a unified diff, and patch applies it to the file you sent. Run your package manager afterwards: the lockfile is yours.

curl -fsSLO https://ripedeps.com/ripedeps.sh
bash ripedeps.sh --min-age 7 package.json | patch -p1
git diff package.json
npm install

Without patch, ask for the whole answer with --json and read diff or updatedPackageJson from it. The options are on the command line page.

Fail a CI job when upgrades are pending

Exit code 3 means "try again", so one retry is worthwhile on a cold cache. The step lists the explanations in the log and fails while at least one package would be upgraded:

curl -fsSLO https://ripedeps.com/ripedeps.sh
plan() { bash ripedeps.sh --json --min-age 7 --skip-adoptconfig package.json > plan.json; }
plan || { [ $? -eq 3 ] && plan; } || exit 1
jq -r '.packages[] | select(.status == "upgrade") | .explanation' plan.json
jq -e '[.packages[] | select(.status == "upgrade")] | length == 0' plan.json

--skip-adoptconfig keeps the ripedeps entry out of the answer, so a file that is otherwise up to date gives an empty plan. See Configuration.

A weekly pull request

The same idea on a schedule: plan, apply the diff, commit and open the pull request yourself. You stay in control of what lands. The complete GitHub Actions workflow is in the API recipes; its core is three lines:

curl -fsSLO https://ripedeps.com/ripedeps.sh
bash ripedeps.sh --min-age 7 package.json | patch -p1
git diff --quiet && exit 0   # nothing to do this week

Everything after that, the branch, the commit and the pull request, is your pipeline's business. The age gate keeps a release from the last few days out of that pull request, so the review is of versions that have had time to settle. See why wait.

GitLab CI

A scheduled job that prints the plan in the job log. It needs only bash, curl and jq:

ripedeps:
  image: node:24
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  before_script:
    - apt-get update -qq && apt-get install -y -qq jq
  script:
    - curl -fsSLO https://ripedeps.com/ripedeps.sh
    - bash ripedeps.sh --min-age 7 --skip-adoptconfig package.json

To open a merge request from the job, apply the diff with patch -p1, commit, and push with the GitLab push options. That needs a token with write access to the repository, which is your decision to make, so Ripedeps does not ask for one.

Monorepos

Ripedeps plans one package.json at a time and reads no workspace configuration. Run it once per file:

curl -fsSLO https://ripedeps.com/ripedeps.sh
for f in $(git ls-files | grep -E '(^|/)package\.json$'); do
  (cd "$(dirname "$f")" && bash "$OLDPWD/ripedeps.sh" --min-age 7 package.json | patch -p1)
done

Each file is planned on its own, so two workspaces that use the same package can end up on different versions. References such as workspace:* are skipped and reported. If versions must match across workspaces, plan the shared package with a focus and review the results together.

Take one package now

When a fix is out and you do not want to wait for the age gate, name the package and set the gate to 0. Only that package and the neighbours it needs move:

bash ripedeps.sh --focus axios --min-age 0 package.json | patch -p1

The explanation names the version and its age, so you can see what you are taking. Ripedeps has no vulnerability data: the advisory that tells you to upgrade comes from you.

With an AI agent

Connect the MCP server to your assistant and ask in plain words, for example "upgrade our dependencies, but keep releases younger than a week out". The agent sends the file, reads the explanation of every package and tells you why something stayed behind. The prompts that work well are in use cases and prompts, and the rules to put in your AGENTS.md are in teach your agent.

Questions? The FAQ has short answers, and Limits and errors lists what to expect from the service.