CLI Commands¶

Complete reference for all depkeeper command-line options. depkeeper provides two main commands -- check and update -- along with global options that apply to both.

Command Overview¶

Both commands share global options described below.

Global Options¶

These options are available for all commands:

depkeeper [OPTIONS] COMMAND [ARGS]...

Verbosity Levels¶

Examples¶

# Use specific config file
depkeeper -c /path/to/config.toml check

# Verbose output
depkeeper -v check
depkeeper -vv check  # Debug level

# Disable colors
depkeeper --no-color check

# Show version
depkeeper --version

check¶

Check for available updates in a requirements file.

Synopsis¶

depkeeper check [OPTIONS] [FILE]

Arguments¶

Options¶

How It Works¶

1. Parse -- Read and parse the requirements file (PEP 440/508 compliant)
2. Query PyPI -- Fetch latest version metadata concurrently via async HTTP
3. Recommend -- Compute safe upgrade targets within major version boundaries
4. Resolve -- Cross-validate recommendations and resolve dependency conflicts
5. Report -- Display results in the requested format

Output Formats¶

Table (default)¶

Human-readable table with colors:

depkeeper check --format table

Package       Current    Latest     Recommended  Status
─────────────────────────────────────────────────────────
requests      2.28.0     2.32.0     2.32.0       Outdated (minor)
flask         2.0.0      3.0.1      2.3.3        Outdated (patch)

Simple¶

One line per package:

depkeeper check --format simple

requests: 2.28.0 -> 2.32.0 (minor)
flask: 2.0.0 -> 2.3.3 (patch)

JSON¶

Machine-readable JSON:

depkeeper check --format json

[
  {
    "name": "requests",
    "status": "outdated",
    "versions": {
      "current": "2.28.0",
      "latest": "2.32.0",
      "recommended": "2.32.0"
    },
    "update_type": "minor"
  }
]

Examples¶

# Basic check
depkeeper check

# Check specific file
depkeeper check requirements-dev.txt

# Show only outdated
depkeeper check --outdated-only

# JSON output for CI
depkeeper check --format json > report.json

# Disable conflict checking (faster)
depkeeper check --no-check-conflicts

# Strict mode: only exact pins
depkeeper check --strict-version-matching

update¶

Update packages to newer versions within safe major version boundaries.

Synopsis¶

depkeeper update [OPTIONS] [FILE]

Arguments¶

Options¶

Update Process¶

1. Parse -- Read the requirements file
2. Check -- Query PyPI for available versions
3. Resolve -- Check for dependency conflicts (if enabled)
4. Preview -- Show proposed changes
5. Confirm -- Ask for user confirmation (unless -y)
6. Backup -- Create backup (if --backup)
7. Apply -- Update the requirements file
8. Report -- Show summary of changes

Backup Files¶

When --backup is used, a timestamped backup is created:

requirements.txt.backup.20260208-143022

Format: {filename}.backup.{YYYYMMDD}-{HHMMSS}

Examples¶

# Basic update (with confirmation)
depkeeper update

# Preview changes
depkeeper update --dry-run

# Update without confirmation
depkeeper update -y

# Create backup before updating
depkeeper update --backup

# Update specific packages only
depkeeper update -p requests -p flask

# Combine options
depkeeper update --backup -y -p requests

# Update specific file
depkeeper update requirements-dev.txt --backup -y

# Disable conflict checking
depkeeper update --no-check-conflicts -y

Command Chaining¶

depkeeper commands can be chained in scripts:

#!/bin/bash
set -e

# Check first
if depkeeper check --outdated-only --format simple | grep -q .; then
    echo "Updates available"

    # Preview
    depkeeper update --dry-run

    # Apply with backup
    depkeeper update --backup -y

    # Verify
    pip install -r requirements.txt
    pytest
fi

Environment Variables¶

Commands respect these environment variables:

Exit Codes¶

See Exit Codes for detailed descriptions and scripting examples.

See Also¶

• Quick Start -- Getting started guide
• Configuration -- Configuration options
• CI/CD Integration -- Pipeline integration
• Exit Codes -- Exit code reference