> ## Documentation Index
> Fetch the complete documentation index at: https://docs.root.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> The Root CLI tools for applying patches and managing registry configuration.

## 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](https://github.com/rootio-avr/rootio_patcher)

For full documentation, see [Root Library Catalog Patcher](/rlc/patcher).

## Installation

Download pre-built binaries from the [GitHub releases page](https://github.com/rootio-avr/rootio_patcher/releases):

**Supported platforms:** Linux x86\_64, macOS (Apple Silicon, Intel), Windows x86\_64

Or build from source (requires Go):

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
export ROOTIO_API_URL=https://api.root.io  # default
```

## Commands

### Python (pip)

```bash theme={null}
# 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:

```bash theme={null}
pip install -r requirements.txt
```

### JavaScript (npm / yarn / pnpm)

```bash theme={null}
# 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:

```bash theme={null}
npm install
# or
yarn install
# or
pnpm install
```

### Java (Maven)

```bash theme={null}
# 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:

```bash theme={null}
mvn clean install
```

## Workflow

The recommended workflow is always to preview before applying:

```bash theme={null}
# 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         |

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

```yaml theme={null}
- 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`                 |

```yaml theme={null}
- 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:**

```yaml theme={null}
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:**

```yaml theme={null}
- 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](https://github.com/rootio-avr/rootio-remediation-action) to apply Root patches to container images in CI/CD:

```yaml theme={null}
- 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 |