CLI

The Paklo CLI is a powerful command-line tool for running Dependabot updates against your repositories. Unlike the extension or hosted version, the CLI gives you complete control over when and where updates run.

Installation

Requirements:

• Node.js 24 or later
• Docker (Docker Desktop on macOS/Windows, Docker Engine on Linux)

Global Installation

npm install -g @paklo/cli
paklo --version

Using npx (No Installation)

npx @paklo/cli --help

Verify Installation

# Check CLI is installed
paklo --version

# Check Docker is running
docker ps

Quick Start

paklo dependabot validate \
  --provider azure \
  --repository-url https://dev.azure.com/my-org/my-project/_git/my-repo \
  --git-token $GIT_ACCESS_TOKEN

paklo dependabot run \
  --provider azure \
  --repository-url https://dev.azure.com/my-org/my-project/_git/my-repo \
  --git-token $GIT_ACCESS_TOKEN \
  --github-token $GITHUB_TOKEN

paklo dependabot cleanup

Commands

validate

Validates your dependabot.yml configuration file against a repository.

paklo dependabot validate [options]

Required Options:

• --provider <PROVIDER> - Repository provider (currently only azure is supported)
• --repository-url <URL> - Repository URL (e.g., https://dev.azure.com/my-org/project/_git/repo)
• --git-token <GIT_TOKEN> - Git provider access token

Example:

paklo dependabot validate \
  --provider azure \
  --repository-url https://dev.azure.com/my-org/my-project/_git/my-repo \
  --git-token $GIT_ACCESS_TOKEN

run

Executes Dependabot updates for the specified repository.

paklo dependabot run [options]

Required Options:

• --provider <PROVIDER> - Repository provider (currently only azure is supported)
• --repository-url <URL> - Repository URL
• --git-token <GIT_TOKEN> - Git provider access token

Optional Options:

Example:

paklo dependabot run \
  --provider azure \
  --repository-url https://dev.azure.com/my-org/my-project/_git/my-repo \
  --git-token $GIT_ACCESS_TOKEN \
  --github-token $GITHUB_TOKEN \
  --auto-approve \
  --set-auto-complete \
  --merge-strategy squash \
  --experiments "record_ecosystem_versions,separate_major_minor_updates" \
  --debug

generate

Generates job config files (job.json and proxy-config.json) for each update entry in a repository's dependabot.yml. Useful for inspecting what Dependabot would run, or for feeding configs into external pipelines.

paklo dependabot generate [options]

Required Options:

• --provider <PROVIDER> - Repository provider (currently only azure is supported)
• --repository-url <URL> - Repository URL
• --git-token <GIT_TOKEN> - Git provider access token

Optional Options:

Output structure:

./job-configs/
  0/
    job.json          # DependabotJobConfig for the updater container
    proxy-config.json # Credentials for the proxy (CA cert is generated at runtime)
  1/
    job.json
    proxy-config.json
  ...

Security-only updates (open-pull-requests-limit: 0) are skipped — they require live vulnerability discovery and cannot be represented as a static config.

Example:

paklo dependabot generate \
  --provider azure \
  --repository-url https://dev.azure.com/my-org/my-project/_git/my-repo \
  --git-token $GIT_ACCESS_TOKEN \
  --out-dir ./job-configs

fetch-metadata

Fetches metadata for a Dependabot pull request. This is useful when you want Dependabot-style pull request metadata outside GitHub Actions, such as in custom automation or CI scripts.

paklo dependabot fetch-metadata [options]

Required Options:

• --provider <PROVIDER> - Repository provider (currently only azure is supported)
• --repository-url <URL> - Repository URL
• --git-token <GIT_TOKEN> - Git provider access token
• --pull-request-id <ID> - Pull request ID to fetch metadata for

Example:

paklo dependabot fetch-metadata \
  --provider azure \
  --repository-url https://dev.azure.com/my-org/my-project/_git/my-repo \
  --git-token $GIT_ACCESS_TOKEN \
  --pull-request-id 123

Example output:

{
  "dependency-names": "lodash",
  "dependency-type": "unknown",
  "update-type": null,
  "updated-dependencies-json": [
    {
      "dependencyName": "lodash",
      "dependencyType": "unknown",
      "updateType": null,
      "directory": "/",
      "packageEcosystem": "npm",
      "targetBranch": "main",
      "prevVersion": "",
      "newVersion": "4.17.21",
      "compatScore": 0,
      "maintainerChanges": false,
      "dependencyGroup": "",
      "ghsaId": "",
      "cvss": 0
    }
  ],
  "directory": "/",
  "package-ecosystem": "npm",
  "target-branch": "main",
  "previous-version": "",
  "new-version": "4.17.21",
  "compatibility-score": 0,
  "maintainer-changes": false,
  "dependency-group": "",
  "ghsa-id": "",
  "cvss": 0
}

fetch-images

Pre-fetch Docker images used by Dependabot. Useful for testing image existence or package manager mapping.

paklo dependabot fetch-images <packageManager>

Required Arguments:

• <packageManager> - The package manager to fetch the updater image for (e.g., npm_and_yarn, bundler, pip, cargo, etc.)

Example:

# Fetch images for npm_and_yarn
paklo dependabot fetch-images npm_and_yarn

# Fetch images for bundler
paklo dependabot fetch-images bundler

This downloads the updater Docker image for the specified package manager and the proxy image.

cleanup

Removes old Docker images and containers created by Dependabot.

paklo dependabot cleanup [options]

Options:

• --cutoff <DURATION> - Remove resources older than duration. Accepts Go duration units: ns, us, ms, s, m, h (e.g., 24h, 30m) | Default: 24h

Examples:

# Remove resources older than 24 hours (default)
paklo dependabot cleanup

# Remove resources older than 48 hours
paklo dependabot cleanup --cutoff 48h

# Remove all Dependabot resources
paklo dependabot cleanup --cutoff 0s

Configuration

The CLI uses standard configuration files. See Configuration for complete options.

Variable Substitution

Use $VARIABLE or ${VARIABLE} syntax for environment variables:

registries:
  private-npm:
    type: npm-registry
    url: https://npm.example.com
    token: $NPM_TOKEN

These will be pulled from environment variables. You'll be prompted for missing variables.

Logging

Set verbosity level:

paklo -v trace dependabot run ...  # Most detailed
paklo -v debug dependabot run ...  # Debug information
paklo -v info dependabot run ...   # Standard (default)
paklo -v warn dependabot run ...   # Warnings only
paklo -v error dependabot run ...  # Errors only

Advanced Usage

Target Specific Updates

Run only certain update configurations:

# Run only the update configurations at index 1 and 3
paklo dependabot run ... --target-update-ids 1,3

Custom Experiments

Enable experimental features:

paklo dependabot run ... --experiments "tidy=true,vendor=true,goprivate=*"

See Experiments for usage patterns.

Inspect Mode

Debug Dependabot API interactions:

paklo dependabot run ... --inspect

Creates ./inspections/ directory with JSON files of API requests and responses.

Dry Run

Test without making changes:

paklo dependabot run ... --dry-run

Performs update checks but doesn't create pull requests.

Proxy Configuration

Configure HTTP/HTTPS proxies:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

Troubleshooting

Common Issues

Docker not running:

Error: Cannot connect to the Docker daemon

Solution: Start Docker Desktop or Docker daemon.

Network connectivity:

Error: getaddrinfo ENOTFOUND

Solution: Check network/proxy configuration. May need to configure proxy environment variables.

Debug Mode

Enable detailed logging:

paklo -v trace dependabot run ... --debug

This provides:

• Docker container logs
• API request/response details
• Detailed error stack traces

Inspect Failed Updates

Use inspect mode to capture API interactions:

paklo dependabot run ... --inspect

Check ./inspections/ for JSON files with request/response data.

Clean Docker State

If updates fail due to Docker issues:

# Remove all Dependabot resources
paklo dependabot cleanup --cutoff 0s