CLI Reference

Version: 2.0.0-alpha.6 Last Updated: 2025-10-13

Complete command-line reference for CLI Audit tool, covering Phase 1 audit commands, Phase 2 installation workflows, and Makefile automation.

Quick Reference
Phase 1: Audit Commands
Environment Variables
Makefile Targets
Phase 2: Python API
Configuration Files
Output Formats
Common Workflows
Troubleshooting

Quick Reference

# Basic audit
python3 cli_audit.py | column -s '|' -t

# Specific tools only
python3 cli_audit.py ripgrep fd bat

# JSON output
CLI_AUDIT_JSON=1 python3 cli_audit.py

# Offline mode
CLI_AUDIT_OFFLINE=1 python3 cli_audit.py

# Snapshot-based workflow
make update      # Collect data (network required)
make audit       # Render table (offline)
make audit-auto  # Update if missing, then render

# System-wide upgrade
make upgrade-all         # Complete 5-stage system upgrade
make upgrade-all-dry-run # Preview without making changes
make check-path          # Validate PATH configuration

# Installation (Makefile)
make install-core
make install-python
make install-node

# Phase 2 API (Python)
from cli_audit import install_tool, bulk_install, upgrade_tool

Phase 1: Audit Commands

Basic Usage

python3 cli_audit.py [OPTIONS] [TOOLS...]

Positional Arguments:

TOOLS: Optional tool names to audit (default: all tools)

Options:

--only TOOL [TOOL ...]: Select specific tools (alias: --tool)
No flags for most options - controlled via environment variables

Tool Selection

# Audit all tools (default)
python3 cli_audit.py

# Audit specific tools
python3 cli_audit.py ripgrep fd bat

# Using --only flag
python3 cli_audit.py --only ripgrep fd bat

# Preset categories
python3 cli_audit.py --only agent-core
python3 cli_audit.py --only python-core
python3 cli_audit.py --only node-core
python3 cli_audit.py --only go-core
python3 cli_audit.py --only infra-core
python3 cli_audit.py --only security-core
python3 cli_audit.py --only data-core

Output Formatting

# Pipe-delimited table (default)
python3 cli_audit.py

# Formatted table with column
python3 cli_audit.py | column -s '|' -t

# Advanced formatting with smart_column
python3 cli_audit.py | python3 smart_column.py -s '|' -t --right 3,5 --header

# JSON array output
CLI_AUDIT_JSON=1 python3 cli_audit.py

# JSON with jq filtering
CLI_AUDIT_JSON=1 python3 cli_audit.py | jq '.[] | select(.status != "UP-TO-DATE")'

# Filter by category
CLI_AUDIT_JSON=1 python3 cli_audit.py | jq '.[] | select(.category == "security")'

Snapshot Workflow

The tool separates data collection (network) from rendering (offline):

# 1. Collect data (writes tools_snapshot.json)
CLI_AUDIT_COLLECT=1 python3 cli_audit.py

# 2. Render from snapshot (no network)
CLI_AUDIT_RENDER=1 python3 cli_audit.py

# Combined: update if missing, then render
make audit-auto

# Manual workflow
make update  # Collect only
make audit   # Render only

Snapshot File:

Default: tools_snapshot.json in project root
Override: CLI_AUDIT_SNAPSHOT_FILE=/path/to/snapshot.json

Offline Mode

# Use only manual cache (upstream_versions.json)
CLI_AUDIT_OFFLINE=1 python3 cli_audit.py

# Offline + render from snapshot
CLI_AUDIT_OFFLINE=1 CLI_AUDIT_RENDER=1 python3 cli_audit.py

Environment Variables

Core Behavior

Variable	Type	Default	Description
`CLI_AUDIT_TIMEOUT_SECONDS`	int	`3`	Network timeout for version checks
`CLI_AUDIT_MAX_WORKERS`	int	`16`	Parallel worker threads
`CLI_AUDIT_OFFLINE`	bool	`0`	Use only manual cache (no network)
`CLI_AUDIT_DEBUG`	bool	`0`	Print debug messages to stderr
`CLI_AUDIT_TRACE`	bool	`0`	Ultra-verbose tracing
`CLI_AUDIT_TRACE_NET`	bool	`0`	Trace network operations

Workflow Modes

Variable	Type	Default	Description
`CLI_AUDIT_COLLECT`	bool	`0`	Collect-only mode (write snapshot)
`CLI_AUDIT_RENDER`	bool	`0`	Render-only mode (read snapshot)
`CLI_AUDIT_FAST`	bool	`0`	Fast mode (skip slow checks)
`CLI_AUDIT_STREAM`	bool	`0`	Stream output as tools complete

Output Formatting

Variable	Type	Default	Description
`CLI_AUDIT_JSON`	bool	`0`	Output JSON array instead of table
`CLI_AUDIT_LINKS`	bool	`1`	Enable OSC 8 hyperlinks
`CLI_AUDIT_EMOJI`	bool	`1`	Use emoji status indicators
`CLI_AUDIT_TIMINGS`	bool	`1`	Show timing information
`CLI_AUDIT_SORT`	string	`order`	Sort mode: `order` or `alpha`
`CLI_AUDIT_GROUP`	bool	`1`	Group output by category

Snapshot Configuration

Variable	Type	Default	Description
`CLI_AUDIT_SNAPSHOT_FILE`	path	`tools_snapshot.json`	Snapshot file path
`CLI_AUDIT_MANUAL_FILE`	path	`upstream_versions.json`	Manual cache path
`CLI_AUDIT_WRITE_MANUAL`	bool	`1`	Auto-update manual cache
`CLI_AUDIT_MANUAL_FIRST`	bool	`0`	Try manual cache before network

Progress and Logging

Variable	Type	Default	Description
`CLI_AUDIT_PROGRESS`	bool	`0`	Show progress messages
`CLI_AUDIT_SLOW_MS`	int	`2000`	Threshold for slow operation warnings

Rate Limiting

Variable	Type	Default	Description
`CLI_AUDIT_HOST_CAP_GITHUB`	int	`4`	Max concurrent GitHub requests
`CLI_AUDIT_HOST_CAP_GITHUB_API`	int	`4`	Max concurrent GitHub API requests
`CLI_AUDIT_HOST_CAP_NPM`	int	`4`	Max concurrent npm registry requests
`CLI_AUDIT_HOST_CAP_CRATES`	int	`4`	Max concurrent crates.io requests
`CLI_AUDIT_HOST_CAP_GNU`	int	`2`	Max concurrent GNU FTP requests

HTTP Behavior

Variable	Type	Default	Description
`CLI_AUDIT_HTTP_RETRIES`	int	`2`	Number of HTTP retry attempts
`CLI_AUDIT_BACKOFF_BASE`	float	`0.2`	Base delay for exponential backoff (seconds)
`CLI_AUDIT_BACKOFF_JITTER`	float	`0.1`	Jitter for backoff randomization (seconds)

Feature Toggles

Variable	Type	Default	Description
`CLI_AUDIT_DOCKER_INFO`	bool	`1`	Check Docker version (may hang in some environments)
`CLI_AUDIT_VALIDATE_MANUAL`	bool	`1`	Validate manual cache entries
`CLI_AUDIT_DPKG_CACHE_LIMIT`	int	`1024`	Max entries in dpkg cache

Tool Selection

Variable	Type	Default	Description
`CLI_AUDIT_ONLY`	string	``	Comma-separated tool names to audit

Authentication

Variable	Type	Default	Description
`GITHUB_TOKEN`	string	``	GitHub personal access token (increases rate limits)

Makefile Targets

Audit Workflows

# Update snapshot (collect-only, network required)
make update

# Render from snapshot (offline)
make audit

# Update if snapshot missing, then render
make audit-auto

# Interactive upgrade guide
make upgrade

System-Wide Upgrade

# Complete system upgrade (5 stages: data → managers → runtimes → user managers → tools)
make upgrade-all

# Preview upgrade without making changes (dry-run)
make upgrade-all-dry-run

# Check PATH configuration before upgrading
make check-path

5-Stage Workflow:

Refresh version data from upstream
Upgrade system package managers (apt, brew, snap, flatpak)
Upgrade language runtimes (Python, Node.js, Go, Ruby, Rust)
Upgrade user package managers (uv, pipx, npm, pnpm, yarn, cargo, composer, poetry)
Upgrade all CLI tools managed by each package manager

Features:

UV migration (auto-migrates pip/pipx packages to uv tools)
System package detection (skips system-managed tools)
Comprehensive logging to logs/upgrade-YYYYMMDD-HHMMSS.log
Colored output with statistics summary

Environment Variables:

DRY_RUN=1 - Preview mode
SKIP_SYSTEM=1 - Skip system package managers
VERBOSE=1 - Detailed output

Installation Scripts

Core Tools:

make install-core      # fd, fzf, ripgrep, jq, yq, bat, delta, just

Language Stacks:

make install-python    # Python toolchain (uv, pipx, poetry)
make install-node      # Node toolchain (nvm, node, npm)
make install-go        # Go toolchain
make install-rust      # Rust toolchain (rustup, cargo)

Infrastructure:

make install-aws       # AWS CLI
make install-kubectl   # Kubernetes CLI
make install-terraform # Terraform
make install-ansible   # Ansible
make install-docker    # Docker
make install-brew      # Homebrew (macOS/Linux)

Update Scripts

make update-core
make update-python
make update-node
make update-go
make update-aws

Uninstall Scripts

make uninstall-node
make uninstall-rust

Reconciliation

# Remove duplicate installations, keep preferred
make reconcile-node    # Remove distro Node, keep nvm-managed
make reconcile-rust    # Remove distro Rust, keep rustup-managed

Permissions

# Make scripts executable
make scripts-perms

Phase 2: Python API

Phase 2 provides programmatic installation, upgrade, and reconciliation APIs.

Quick Start:

from cli_audit import install_tool, Config, Environment

config = Config()
env = Environment.detect()

result = install_tool(
    tool_name="ripgrep",
    package_name="ripgrep",
    target_version="latest",
    config=config,
    env=env,
    language="rust",
)

See Also:

PHASE2_API_REFERENCE.md - Complete Phase 2 API documentation
README.md - Code examples for installation, upgrades, and reconciliation

Configuration Files

YAML Configuration

Create .cli-audit.yml in your project root, ~/.config/cli-audit/config.yml, or /etc/cli-audit/config.yml.

Precedence: Project → User → System → Defaults

Example:

version: 1

environment:
  mode: workstation  # auto, ci, server, or workstation

tools:
  black:
    version: "24.*"  # Pin to major version
    method: pipx     # Preferred package manager
    fallback: pip    # Fallback if primary fails

  ripgrep:
    version: latest
    method: cargo

preferences:
  reconciliation: aggressive  # parallel or aggressive
  breaking_changes: warn      # accept, warn, or reject
  auto_upgrade: true
  timeout_seconds: 10
  max_workers: 8
  cache_ttl_seconds: 3600     # 1 hour version cache

  bulk:
    fail_fast: false
    auto_rollback: true
    generate_rollback_script: true

  package_managers:
    python:
      - uv
      - pipx
      - pip
    rust:
      - cargo

presets:
  dev-essentials:
    - black
    - ripgrep
    - fd
    - bat

Configuration Validation:

from cli_audit import load_config, validate_config

config = load_config(custom_path=".my-config.yml")
warnings = validate_config(config)

for warning in warnings:
    print(f"⚠️  {warning}")

Output Formats

Table Format (Default)

state|tool|installed|installed_method|latest_upstream|upstream_method
+|fd|9.0.0 (140ms)|apt/dpkg|9.0.0 (220ms)|github
⚠|ripgrep|13.0.0 (120ms)|cargo|14.1.1 (180ms)|github
✗|bat|X|N/A|0.24.0 (200ms)|github

Fields:

state: Status indicator
- + or ✓: Up-to-date
- ⚠: Outdated
- ✗ or -: Not installed
- ?: Unknown (check failed)
tool: Tool name
installed: Local version (with timing if CLI_AUDIT_TIMINGS=1)
installed_method: Installation source
- uv tool, pipx/user, cargo, npm (user), apt/dpkg, etc.
latest_upstream: Latest version upstream
upstream_method: Source of latest version
- github, pypi, crates, npm, gnu-ftp, manual

JSON Format

CLI_AUDIT_JSON=1 python3 cli_audit.py

Schema:

{
  "tool": "ripgrep",
  "installed": "13.0.0 (120ms)",
  "installed_version": "13.0.0",
  "installed_method": "cargo",
  "installed_path_resolved": "/home/user/.cargo/bin/rg",
  "classification_reason": "path-under-~/.cargo/bin",
  "installed_path_selected": "/home/user/.cargo/bin/rg",
  "classification_reason_selected": "path-under-~/.cargo/bin",
  "latest_upstream": "14.1.1 (180ms)",
  "latest_version": "14.1.1",
  "upstream_method": "github",
  "status": "OUTDATED",
  "category": "core",
  "description": "Fast search tool"
}

Status Values:

UP-TO-DATE: Installed version matches latest
OUTDATED: Newer version available
NOT INSTALLED: Tool not found
UNKNOWN: Version check failed

Snapshot Format

File: tools_snapshot.json

{
  "__meta__": {
    "schema_version": 1,
    "created_at": "2025-10-13T10:30:00Z",
    "offline": false,
    "count": 50,
    "partial_failures": 2
  },
  "tools": [
    {
      "tool": "ripgrep",
      "installed": "13.0.0",
      "latest_upstream": "14.1.1",
      "status": "OUTDATED",
      ...
    }
  ]
}

Common Workflows

Quick Agent Readiness Check

# Table scan
python3 cli_audit.py | column -s '|' -t

# Filter outdated tools
CLI_AUDIT_JSON=1 python3 cli_audit.py \
  | jq -r '.[] | select(.status != "UP-TO-DATE") | [.tool, .status] | @tsv'

# Security tools only
CLI_AUDIT_JSON=1 python3 cli_audit.py \
  | jq '.[] | select(.category == "security")'

Offline Development

# Before going offline: collect snapshot
make update

# Offline: render from snapshot
CLI_AUDIT_OFFLINE=1 make audit

# Or combined
CLI_AUDIT_OFFLINE=1 make audit-auto

CI/CD Integration

# Fast audit in CI (no timing info, fail on outdated)
CLI_AUDIT_TIMINGS=0 CLI_AUDIT_FAST=1 python3 cli_audit.py > audit.txt

# JSON for automation
CLI_AUDIT_JSON=1 python3 cli_audit.py > audit.json

# Parse results
OUTDATED=$(jq -r '.[] | select(.status == "OUTDATED") | .tool' audit.json)
if [ -n "$OUTDATED" ]; then
    echo "Outdated tools: $OUTDATED"
    exit 1
fi

Custom Tool Selection

# Python ecosystem only
python3 cli_audit.py --only python-core

# Multiple categories
python3 cli_audit.py --only agent-core security-core

# Specific tools
python3 cli_audit.py ripgrep fd bat delta

# Using environment variable
CLI_AUDIT_ONLY="ripgrep,fd,bat" python3 cli_audit.py

Performance Optimization

# Fast mode (skip slow checks)
CLI_AUDIT_FAST=1 python3 cli_audit.py

# Reduce workers for slow network
CLI_AUDIT_MAX_WORKERS=4 python3 cli_audit.py

# Increase timeout for slow hosts
CLI_AUDIT_TIMEOUT_SECONDS=10 python3 cli_audit.py

# Use manual cache first (faster)
CLI_AUDIT_MANUAL_FIRST=1 python3 cli_audit.py

Debugging

# Basic debug output
CLI_AUDIT_DEBUG=1 python3 cli_audit.py 2> debug.log

# Verbose tracing
CLI_AUDIT_TRACE=1 python3 cli_audit.py 2> trace.log

# Network tracing
CLI_AUDIT_TRACE_NET=1 python3 cli_audit.py 2> network.log

# Progress messages
CLI_AUDIT_PROGRESS=1 python3 cli_audit.py

Troubleshooting

Network Issues

Problem: Timeouts or slow responses

# Increase timeout
CLI_AUDIT_TIMEOUT_SECONDS=10 python3 cli_audit.py

# Reduce concurrency
CLI_AUDIT_MAX_WORKERS=4 python3 cli_audit.py

# Cap per-host requests
CLI_AUDIT_HOST_CAP_GITHUB=2 CLI_AUDIT_HOST_CAP_NPM=2 python3 cli_audit.py

Problem: GitHub rate limits

# Use personal access token
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
python3 cli_audit.py

# Use offline mode
CLI_AUDIT_OFFLINE=1 python3 cli_audit.py

Missing Tools

Problem: Tool shows as "NOT INSTALLED" but is actually installed

# Check PATH
echo $PATH

# Check extra search paths
CLI_AUDIT_DEBUG=1 python3 cli_audit.py 2>&1 | grep -i "search"

# Tool-specific paths (edit cli_audit.py)
TOOL_SPECIFIC_PATHS = {
    "mytool": ["/custom/path/to/tool"],
}

Version Detection

Problem: Installed version shows as "X" or "unknown"

# Debug version detection
CLI_AUDIT_DEBUG=1 python3 cli_audit.py mytool 2> debug.log

# Check tool's version flag manually
mytool --version
mytool -v
mytool version

Snapshot Issues

Problem: Stale snapshot data

# Force snapshot update
rm tools_snapshot.json
make update

# Or use CLI flags
CLI_AUDIT_COLLECT=1 python3 cli_audit.py

Problem: Corrupted snapshot

# Validate JSON
jq '.' tools_snapshot.json

# Rebuild from scratch
rm tools_snapshot.json upstream_versions.json
make update

Performance

Problem: Slow audit execution

# Check slow operations
CLI_AUDIT_TRACE=1 python3 cli_audit.py 2>&1 | grep "slow"

# Use fast mode
CLI_AUDIT_FAST=1 python3 cli_audit.py

# Use snapshot workflow
make update  # Once, when needed
make audit   # Fast, offline rendering

Docker Hangs

Problem: Docker version check hangs

# Disable Docker info
CLI_AUDIT_DOCKER_INFO=0 python3 cli_audit.py

Uh oh!

FilesExpand file tree

CLI_REFERENCE.md

Latest commit

History

CLI_REFERENCE.md

File metadata and controls

CLI Reference

Table of Contents

Quick Reference

Phase 1: Audit Commands

Basic Usage

Tool Selection

Output Formatting

Snapshot Workflow

Offline Mode

Environment Variables

Core Behavior

Workflow Modes

Output Formatting

Snapshot Configuration

Progress and Logging

Rate Limiting

HTTP Behavior

Feature Toggles

Tool Selection

Authentication

Makefile Targets

Audit Workflows

System-Wide Upgrade

Installation Scripts

Update Scripts

Uninstall Scripts

Reconciliation

Permissions

Phase 2: Python API

Configuration Files

YAML Configuration

Output Formats

Table Format (Default)

JSON Format

Snapshot Format

Common Workflows

Quick Agent Readiness Check

Offline Development

CI/CD Integration

Custom Tool Selection

Performance Optimization

Debugging

Troubleshooting

Network Issues

Missing Tools

Version Detection

Snapshot Issues

Performance

Docker Hangs

Related Documentation