resq-cli

Unified developer CLI for the ResQ platform. Provides commands for license header management, security auditing, secret scanning, dependency cost analysis, image placeholder generation, documentation export, monorepo versioning, and launching a suite of interactive TUI tools.

Overview

resq is the single entry point for all ResQ developer tooling. It wraps standalone TUI applications (logs, health, deploy, perf, clean, asm) and provides built-in commands for CI workflows, pre-commit hooks, and repository maintenance.

graph TD
    resq["resq (CLI)"]

    resq --> copyright["copyright"]
    resq --> lqip["lqip"]
    resq --> audit["audit"]
    resq --> cost["cost"]
    resq --> secrets["secrets"]
    resq --> tree_shake["tree-shake"]
    resq --> pre_commit["pre-commit"]

    resq --> dev["dev"]
    dev --> kill_ports["dev kill-ports"]
    dev --> sync_env["dev sync-env"]
    dev --> upgrade["dev upgrade"]
    dev --> install_hooks["dev install-hooks"]

    resq --> version["version"]
    version --> version_add["version add"]
    version --> version_apply["version apply"]
    version --> version_check["version check"]

    resq --> docs["docs"]

    resq --> explore["explore (resq-perf)"]
    resq --> logs["logs (resq-logs)"]
    resq --> health["health (resq-health)"]
    resq --> deploy["deploy (resq-deploy)"]
    resq --> clean["clean (resq-clean)"]
    resq --> asm["asm (resq-bin)"]

    style resq fill:#2563eb,color:#fff
    style dev fill:#7c3aed,color:#fff
    style version fill:#7c3aed,color:#fff
    style explore fill:#059669,color:#fff
    style logs fill:#059669,color:#fff
    style health fill:#059669,color:#fff
    style deploy fill:#059669,color:#fff
    style clean fill:#059669,color:#fff
    style asm fill:#059669,color:#fff

Legend: Blue = entry point, Purple = commands with subcommands, Green = TUI launchers.

Installation

# Build from the workspace root
cargo build --release -p resq-cli

# Install globally
cargo install --path cli

# Or use the cargo alias (defined in .cargo/config.toml)
cargo resq help

The binary is installed as resq at target/release/resq.

Cargo Aliases

The following workspace aliases are defined in .cargo/config.toml:

Commands

copyright -- License Header Management

Adds or checks copyright/license headers across all source files in the repository. Supports multiple comment styles (C-style block, XML/HTML, hash-line, double-dash, Elisp, AsciiDoc). Shebangs (#!/...) are always preserved at line 0.

Arguments

Examples

# Check all tracked files (CI -- exits 1 if any missing)
resq copyright --check

# Preview what would be added without writing
resq copyright --dry-run

# Add headers to all files missing them
resq copyright

# Overwrite existing headers with a different license and author
resq copyright --force --license apache-2.0 --author "Acme Corp" --year 2026

# Process only Rust and TypeScript files
resq copyright --ext rs,ts

# Process files matching a glob pattern
resq copyright --glob "crates/**/*.rs"

lqip -- Low-Quality Image Placeholders

Generates tiny base64-encoded data URIs from images for use as blur-up placeholders in web applications. Supports JPEG, PNG, and WebP formats.

Arguments

Examples

# Single image -- prints data URI
resq lqip --target hero.jpg

# Directory of images -- text list
resq lqip --target public/images/

# Recursive with JSON output
resq lqip --target public/ --recursive --format json

# Custom dimensions
resq lqip --target photo.png --width 32 --height 24

audit -- Security & Quality Audit

Three-pass security and quality sweep covering all language ecosystems. Runs Google OSV Scanner (cross-ecosystem), npm audit-ci, and React Doctor.

Arguments

Examples

# Full audit (all three passes)
resq audit

# Run only the OSV Scanner pass
resq audit --skip-npm --skip-react

# Strict npm audit (fail on moderate)
resq audit --skip-osv --skip-react --level moderate

# OSV Scanner with JSON output
resq audit --skip-npm --skip-react --osv-format json

# React Doctor with custom threshold and diff mode
resq audit --skip-osv --skip-npm --react-min-score 90 --react-diff main

cost -- Dependency Size Analysis

Fetches package sizes from registries (npm, crates.io, PyPI) and categorizes dependencies by download footprint into high (>10 MB), medium (1-10 MB), and low (<1 MB) buckets. Results are saved as JSON files.

Arguments

Examples

# Auto-detect project type and analyze
resq cost

# Analyze a specific project directory
resq cost --root services/coordination-hce

# Force Rust analysis and custom output
resq cost --project-type rust --output reports/deps

secrets -- Secret Scanner

Scans source files for hardcoded credentials, API keys, private keys, tokens, and high-entropy strings. Uses pattern matching with entropy analysis (Shannon entropy with charset-specific thresholds for hex, base64, and alphanumeric strings) and Aho-Corasick multi-pattern matching for performance.

Arguments

Examples

# Scan all git-tracked files (default)
resq secrets

# Only scan staged changes (pre-commit hook)
resq secrets --staged

# Scan with history and allowlist
resq secrets --history --since "v1.0.0" --allowlist .secrets-allowlist

# Verbose output showing matched content
resq secrets --verbose

tree-shake -- TypeScript Dead Code Removal

Runs tsr to remove unused TypeScript exports from project entry points. Requires bun to be installed.

Arguments

This command takes no arguments.

Examples

resq tree-shake

dev -- Development Utilities

Unified entry point for repository-level development tasks.

Subcommands

dev kill-ports -- Kill Processes on Ports

Finds and terminates processes listening on specified TCP ports.

# Kill process on port 3000
resq dev kill-ports 3000

# Kill range of ports without confirmation
resq dev kill-ports 8000..8010 --yes

# Force kill
resq dev kill-ports 3000 --force

dev sync-env -- Sync Environment Variables to turbo.json

Scans .env.example files across the monorepo and synchronizes discovered environment variable names into turbo.json task configurations.

# Sync all environment variables
resq dev sync-env

# Preview changes
resq dev sync-env --dry-run

# Sync only for build and dev tasks
resq dev sync-env --tasks build,dev

dev upgrade -- Upgrade Dependencies

Upgrades dependencies across all language silos in the monorepo (Python/uv, Rust/cargo, JS/bun, C++/Conan, C#/dotnet, Nix).

# Upgrade all ecosystems
resq dev upgrade

# Upgrade only Rust dependencies
resq dev upgrade rust

# Upgrade only JavaScript dependencies
resq dev upgrade js

dev install-hooks -- Install Git Hooks

Configures git core.hooksPath to point at the .git-hooks directory and makes all hook scripts executable.

resq dev install-hooks

pre-commit -- Unified Pre-Commit Hook

Runs a suite of checks suitable for a git pre-commit hook: copyright headers, secret scanning, formatting, audits, and versioning prompts. Includes an interactive TUI progress display.

Arguments

Examples

# Run all pre-commit checks
resq pre-commit

# Skip audit and formatting (fast mode)
resq pre-commit --skip-audit --skip-format

# CI-friendly plain output
resq pre-commit --no-tui

version -- Monorepo Versioning

Manages package versions and changesets across the monorepo using a changeset-based workflow. Supports Cargo.toml, package.json, pyproject.toml, and Directory.Build.props manifests.

Subcommands

version add -- Create a Changeset

resq version add --bump minor --message "Add new health check endpoint"

version apply -- Apply Version Bumps

Consumes all pending changesets, determines the highest bump level, updates all manifests, and appends to CHANGELOG.md.

# Apply version bumps
resq version apply

# Preview only
resq version apply --dry-run

version check -- Verify Version Sync

Checks that all manifest files contain the same version string.

resq version check

docs -- Documentation Export

Exports and publishes OpenAPI specifications from the Infrastructure API and Coordination HCE services.

Arguments

Examples

# Export specs locally
resq docs --export-only

# Export and publish to GitHub
resq docs --publish

# Preview what would happen
resq docs --dry-run

TUI Launchers

These commands launch standalone TUI applications from the ResQ workspace. Each delegates to a separate binary via cargo run -p <tool>.

explore -- Performance Monitor (resq-perf)

resq explore
resq explore http://localhost:8080/status --refresh-ms 1000

logs -- Log Aggregator (resq-logs)

resq logs
resq logs --source file --service edge-aeai

health -- Health Dashboard (resq-health)

resq health
resq health --interval 10

deploy -- Deployment Manager (resq-deploy)

resq deploy
resq deploy --env staging --k8s

clean -- Workspace Cleaner (resq-clean)

resq clean
resq clean --dry-run

asm -- Binary Analyzer (resq-bin)

resq asm --file target/release/resq
resq asm --dir target/release/ --recursive --ext .so
resq asm --file mylib.o --plain --no-cache
resq asm --dir . --recursive --json --max-functions 100

Environment Variables

The pre-commit and audit commands shell out to external tools (osv-scanner, bun, npx, audit-ci, react-doctor) which may read their own environment variables.

Configuration

• Project root detection: The CLI walks up the directory tree looking for resQ.sln, package.json, Cargo.toml, pyproject.toml, or .git to locate the project root.
• Gitignore integration: The secrets and copyright commands parse .gitignore for directory exclusion. When .gitignore is missing, a built-in fallback list is used (node_modules, .git, dist, build, .next, target, __pycache__, .venv, venv, vendor, .turbo, coverage).
• OSV Scanner config: If osv-scanner.toml exists at the project root, it is passed automatically to the audit command.
• Secrets allowlist: Create a text file with one pattern per line and pass it via --allowlist.
• Changesets: Version changesets are stored as markdown files in .changesets/ at the repository root.

Exit Codes

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.