CLI Reference

rootio_patcher

rootio_patcher is Root’s open-source CLI tool for applying security patches to your project’s dependencies. It scans installed packages and applies fixes from Root’s vulnerability database - modifying your requirements.txt, package.json, or pom.xml without changing package versions unless necessary. Source: github.com/rootio-avr/rootio_patcher For full documentation, see Root Library Catalog Patcher.

Installation

Download pre-built binaries from the GitHub releases page: Supported platforms: Linux x86_64, macOS (Apple Silicon, Intel), Windows x86_64 Or build from source (requires Go):

git clone https://github.com/rootio-avr/rootio_patcher
cd rootio_patcher
go build -o rootio_patcher .

Authentication

Set your API token before running any commands:

export ROOTIO_API_KEY=your-api-token

Obtain your API token from the Root platform under Settings → Token Management → Generate API Token. Optionally override the API endpoint:

export ROOTIO_API_URL=https://api.root.io  # default

Commands

Python (pip)

# Preview patches (dry-run mode - default)
rootio_patcher pip remediate

# Apply patches
rootio_patcher pip remediate --dry-run=false

# Specify a Python interpreter
rootio_patcher pip remediate --python-path=/usr/bin/python3 --dry-run=false

# Use Root.io aliased package names (default: true)
rootio_patcher pip remediate --use-alias=true --dry-run=false

After applying patches, reinstall your packages:

pip install -r requirements.txt

JavaScript (npm / yarn / pnpm)

# Preview patches
rootio_patcher npm remediate

# Apply patches - specify your package manager
rootio_patcher npm remediate --package-manager=npm --dry-run=false
rootio_patcher npm remediate --package-manager=yarn --dry-run=false
rootio_patcher npm remediate --package-manager=pnpm --dry-run=false

After applying, run your package manager’s install:

npm install
# or
yarn install
# or
pnpm install

Java (Maven)

# Preview patches
rootio_patcher maven remediate

# Apply patches
rootio_patcher maven remediate --dry-run=false

# Specify a custom pom.xml path
rootio_patcher maven remediate --file=path/to/pom.xml --dry-run=false

After applying, rebuild:

mvn clean install

Workflow

The recommended workflow is always to preview before applying:

# Step 1: Preview
rootio_patcher pip remediate
# Review output - which packages will be patched, which CVEs addressed

# Step 2: Apply
rootio_patcher pip remediate --dry-run=false

# Step 3: Reinstall
pip install -r requirements.txt

Flags Reference

Flag	Default	Description
`--dry-run`	`true`	Preview changes without modifying files
`--use-alias`	`true`	(pip) Use Root.io-branded package aliases
`--python-path`	system Python	(pip) Path to Python interpreter
`--package-manager`	-	(npm) Select `npm`, `yarn`, or `pnpm`
`--file`	`pom.xml`	(maven) Path to Maven config file
`--ignore`	-	Exclude `package@version` from patching (repeatable, comma-separated). Merged with a `.rootioignore` file. See Ignoring Packages.

Exit Codes

When running in dry-run mode (the default), rootio_patcher exits with a code indicating the outcome. Use this to gate pipelines without modifying any files.

Exit code	Meaning
`0`	No patches needed — all packages are up to date
`1`	Error (bad config, API failure, unexpected panic)
`2`	Patches are available — action required

GitHub Actions

rootio-patch (vulnerability check)

A reusable composite action runs rootio_patcher in dry-run mode and fails the job if patches are available (exit code 2). No files are modified.

- uses: rootio-avr/rootio_patcher/.github/actions/rootio-patch@main
  with:
    api-key: ${{ secrets.ROOTIO_API_KEY }}
    ecosystem: npm   # pip | npm | maven

Inputs:

Input	Required	Default	Description
`api-key`	Yes	—	Root.io API key
`ecosystem`	Yes	—	`pip`, `npm`, or `maven`
`working-directory`	No	`.`	Repo subdirectory to run in
`package-manager`	No	`npm`	(npm) `npm`, `yarn`, or `pnpm`
`directory`	No	`.`	(npm) Project directory containing the lock file
`python-path`	No	`python`	(pip) Path to Python interpreter
`use-alias`	No	`true`	(pip) Use Root.io aliased packages
`file`	No	`pom.xml`	(maven) Path to `pom.xml`

Outputs:

Output	Description
`patches-available`	`"true"` if patches were found, `"false"` if everything is up to date

Environment variables: Advanced settings are not action inputs — pass them as env: on the step:

Variable	Default	Description
`ROOTIO_API_URL`	`https://api.root.io`	Override the Root.io API endpoint
`ROOTIO_PKG_URL`	`https://pkg.root.io`	Override the Root.io package registry URL
`ROOTIO_PIP_INDEX_URL`	—	(pip) Full pip `--index-url`; bypasses `ROOTIO_PKG_URL` construction
`LOG_LEVEL`	`info`	Logging verbosity: `debug`, `info`, `warn`, or `error`

- uses: rootio-avr/rootio_patcher/.github/actions/rootio-patch@main
  env:
    ROOTIO_PKG_URL: https://pkg.your-mirror.example.com
    ROOTIO_PIP_INDEX_URL: https://pkg.your-mirror.example.com/pypi/simple/
  with:
    api-key: ${{ secrets.ROOTIO_API_KEY }}
    ecosystem: pip

Example — block a PR if vulnerabilities exist:

name: Security Check
on: [pull_request]
jobs:
  vuln-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: rootio-avr/rootio_patcher/.github/actions/rootio-patch@main
        with:
          api-key: ${{ secrets.ROOTIO_API_KEY }}
          ecosystem: npm
          package-manager: npm

Example — warn without blocking:

- uses: rootio-avr/rootio_patcher/.github/actions/rootio-patch@main
  id: vuln-check
  continue-on-error: true
  with:
    api-key: ${{ secrets.ROOTIO_API_KEY }}
    ecosystem: npm
- if: steps.vuln-check.outputs.patches-available == 'true'
  run: echo "Patches available — consider remediating soon."

rootio-remediation-action (container image patching)

Use the rootio-remediation-action to apply Root patches to container images in CI/CD:

- name: Remediate image with Root
  uses: rootio-avr/rootio-remediation-action@v1
  with:
    image_reference: your-registry/your-app:latest
    org_id: ${{ env.ROOTIO_ORG_ID }}
    api_token: ${{ secrets.ROOTIO_API_TOKEN }}
    registry_credentials_id: ${{ env.ROOTIO_REGISTRY_CREDENTIALS }}

Outputs:

Output	Description
`result_image`	The patched image name
`process_status`	Overall remediation status
`remediation_decision`	Whether the system proceeded with patching
`image_created`	Boolean - whether a new patched image was produced

​rootio_patcher

​Installation

​Authentication

​Commands

​Python (pip)

​JavaScript (npm / yarn / pnpm)

​Java (Maven)

​Workflow

​Flags Reference

​Exit Codes

​GitHub Actions

​rootio-patch (vulnerability check)

​rootio-remediation-action (container image patching)