Cargo Mate

A Rust development companion that enhances cargo with intelligent workflows, state management, performance optimization, and comprehensive project monitoring. W.I.P. UNDER DEVELOPMENT!

Table of Contents

• Quick Start
• Installation
• Command Reference
  • Version Commands
  • View Commands
  • Log Commands
  • Journey Commands
  • Anchor Commands
  • Tide Commands
  • Deps Commands
  • LIBerate Commands
  • Tree Commands
  • Stub Commands
  • Bin Commands
  • Scrub Commands
  • SCAT Commands
  • Strip Commands
  • Sweep Commands
  • Map Commands
  • Probe Commands
  • Mutiny Commands
  • Config Commands
  • Optimize Commands
  • Checklist Commands
  • WTF Commands
  • Tool Commands
  • DDR Commands
  • General Commands
• Project Configuration (.cg)
• Global Configuration (~/.shipwreck/config.toml)
• Examples
• License

Version Commands

cm version                 # Display overview of version management capabilities and current version
cm version init [<ver>]    # Initialize semantic versioning system with optional starting version number
cm version info            # Show detailed information about current version and version management status
cm version increment <type> # Increase version number by patch, minor, or major increment type
cm version set <version>   # Manually assign a specific version number to the project
cm version history         # Display chronological list of all version changes and releases
cm version update-cargo    # Synchronize version number from version management into Cargo.toml file
cm version config enable   # Activate automatic version incrementation on successful builds
cm version config disable  # Deactivate automatic version incrementation feature
cm version config policy   # Configure the rules for automatic version incrementation behavior
cm version config show     # Display current version management configuration settings

cargo publish and cargo build auto version

View Commands

cm view                    # Display overview of all available viewing and monitoring capabilities
cm view errors             # Show comprehensive list of all current compilation errors and warnings
cm view artifacts          # Display locations and details of all generated build artifacts and files
cm view scripts            # Show outputs and results from executed build scripts
cm view history            # Present detailed chronological history of all build operations and results
cm view checklist          # Display actionable checklist of errors with suggested fixes and solutions
cm view all                # Show consolidated view of all build results, errors, and artifacts in one interface
cm view latest             # Provide quick overview of most recent build issues and problems
cm view open               # Launch file explorer to navigate and examine build result locations

Captain's Log Commands (Natural language build notes with automatic tagging and search.)

cm log                     # Display overview of all project log entries and logging capabilities
cm log add <message>       # Record a new timestamped log entry with custom message for project tracking
cm log search <query>      # Find log entries containing specific keywords or phrases
cm log timeline <days>     # Show chronological view of log entries for specified number of recent days
cm log export <path>       # Save all log entries to external file format for backup or analysis
cm log analyze             # Examine log patterns and generate statistics about project activity

Journey Commands

cm journey                 # Show overview of all recorded command sequences and available actions
cm journey record <name>   # Begin recording a new command sequence for later playback
cm journey play <name>     # Execute a previously recorded command sequence exactly as recorded
cm journey list            # Display all locally stored recorded command sequences
cm journey export <name>   # Save a recorded command sequence to an external file for sharing or backup
cm journey import <path>   # Load a previously exported command sequence into local storage
cm journey publish <name>  # Share a command sequence publicly on the marketplace for others to use
cm journey download <id>   # Download and install a publicly shared command sequence from the marketplace
cm journey search <query>  # Find command sequences in the public marketplace matching your search terms
cm journey published       # Display all command sequences you've published to the marketplace

Anchor Commands

cm anchor                  # Display overview of all saved project snapshots and available operations
cm anchor save <name>      # Create a complete snapshot of current project state including files and dependencies
cm anchor restore <name>   # Return project to exact state captured in specified snapshot
cm anchor list             # Show all available project snapshots with metadata and timestamps
cm anchor show <name>      # Display detailed information about a specific project snapshot
cm anchor diff <name>      # Compare current project state with saved snapshot to identify changes
cm anchor auto <name>      # Enable automatic background saving of project changes to specified snapshot
cm anchor stop <name>      # Disable automatic saving for the specified snapshot

Tide Commands

cm tide                    # Display overview of performance tracking and analytics capabilities
cm tide show               # Present interactive charts and graphs of build performance metrics over time
cm tide analyze            # Examine project dependencies and their impact on build performance
cm tide export <path>      # Save performance metrics and analytics data to external file format

Deps Commands

cm deps                    # Analyze project dependencies - find which external crates are actually used vs declared
cm deps --path <PATH>      # Analyze specific directory (default: current directory)
cm deps --json             # Output results in JSON format for programmatic consumption

# What it does:
# - Scans all Rust source files (src/**/*.rs and build.rs)
# - Extracts use statements and extern crate declarations
# - Parses Cargo.toml to get declared dependencies
# - Compares used crates vs declared dependencies
# - Queries crates.io to verify missing dependencies exist
# - Reports unused declared dependencies and missing used dependencies

LIBerate Commands

cm liberate                # Generate lib.rs by scanning all Rust files and extracting public items
cm liberate -t <PATH>      # Target directory to scan (default: current directory)
cm liberate -o <PATH>      # Output file path (default: .LIBerate-[timestamp].rs)

# What it does:
# - Recursively scans project directory for all .rs files
# - Extracts all public items (structs, enums, functions, constants, types, traits, statics, unions, impl blocks)
# - Generates module declarations for each file
# - Creates pub use statements for all public items
# - Organizes exports by category with helpful comments
# - Handles errors gracefully with informative warnings

Tree Commands

cm tree                    # Generate beautiful markdown-formatted directory tree
cm tree -t <PATH>          # Target directory to scan (default: current directory)
cm tree -o <PATH>          # Output file path (default: cm-tree-[timestamp].md)
cm tree --file-size        # Include file sizes
cm tree --line-count       # Count lines in files
cm tree --dates            # Include modification dates
cm tree --style <STYLE>    # Choose style: basic, readme, cm, hard, easy (default: readme)
cm tree --yolo             # Activate YOLO mode 🎉
cm tree history            # View all previously generated trees
cm tree show <name>        # Display a specific tree from history
cm tree find <query>       # Search through tree history

Stub Commands

cm stub                    # Scan for stubs, placeholders, TODOs, FIXMEs, and unimplemented code patterns
cm stub -t <PATH>          # Target directory to scan (default: current directory)
cm stub -o <PATH>          # Output file path (default: cm-stubs-[timestamp].md)
cm stub --ext <EXT>        # File extensions to scan (default: rs,py,js,html)
cm stub --custom <PATTERN> # Custom pattern(s) to search for (comma-separated)
cm stub --skip <PATTERNS>  # Patterns to skip/exclude (comma-separated)
cm stub find [<pattern>]   # Search for stubs with optional custom pattern
cm stub skip <patterns>    # Search while skipping specific patterns
cm stub history            # View all previously generated stub reports
cm stub show <name>        # Display a specific stub report from history
cm stub delete --all       # Delete all stub reports from history

Bin Commands

cm bin --name <NAME>       # Test binary by name (searches PATH)
cm bin --path <PATH>       # Test binary by path
cm bin -o <PATH>           # Output file path (default: cm-bin-{name}-{timestamp}.md)
cm bin --timeout-seconds <SECONDS>  # Timeout for each command (default: 10)
cm bin --max-depth <DEPTH> # Maximum number of commands to test
cm bin history             # View all previously generated test reports
cm bin show <name>         # Display a specific test report from history
cm bin find <query>        # Search through test reports
cm bin delete --all        # Delete all test reports from history

# What it does:
# - Runs --help, -h, or help to discover commands
# - Parses help output to extract available commands
# - For each command, gets its help to extract flags
# - Tests each command with each flag combination
# - Collects all outputs, exit codes, and errors
# - Generates comprehensive markdown report

Scrub Commands

cm scrub run --directory -d <dir>         # Directory to start searching from (default: current)
cm scrub run --dry-run -n                 # Show what would be cleaned without actually cleaning
cm scrub run --verbose -v                 # Enable verbose output
cm scrub run --resume-from -r <string>    # Resume from projects containing this string
cm scrub run --min-depth <num>            # Minimum directory depth to search
cm scrub run --max-depth <num>            # Maximum directory depth to search
cm scrub run --jobs -j <num>              # Number of parallel workers (default: 4)
cm scrub run --min-size <MB>              # Only show projects larger than this size (MB)
cm scrub run --sort-by-size -s            # Sort results by size
cm scrub run --export-json <file>         # Export results to JSON file
cm scrub run --interactive -i             # Ask before cleaning each project
cm scrub run --exclude -e <pattern>       # Exclude directories matching patterns (multiple)
cm scrub run --stats-only                 # Only show statistics without cleaning

SCAT Commands (Source Code Obfuscation Tool) STILL UNDER DEVELOPMENT - SCAT AT YOUR OWN RISK

cm scat                    # Display overview of SCAT obfuscation capabilities
cm scat names <PATH>       # Obfuscate file/folder names with mapping file
cm scat code <PATH>        # Obfuscate Rust identifiers while preserving functionality
cm scat strings <PATH>     # Scramble string literals with encryption key
cm scat pack <INPUT> <OUTPUT> # Pack files into obfuscated bundle
cm scat unpack <INPUT> <MAP> # Reverse obfuscation using mapping files

# Examples:
cm scat names src/ --map name_mapping.json --sequential
cm scat code src/ --preserve-pub --min-len 3 --map code_mapping.json
cm scat strings src/ --key "contest_key" --map strings.json
cm scat pack src/ contest.bundle --compress
cm scat unpack obfuscated/ name_mapping.json --output original/

Strip Commands (Code Cleaning & Optimization) - SOMETIMES TEASE HURTS

cm strip <INPUT>           # Remove comments and non-essential elements from Rust files
cm strip --tease           # strips maticulously comments and blank lines by file or directory 
cm strip <INPUT> -o <FILE> # Strip to output file (defaults to stdout)
cm strip <INPUT> -r        # Process directory recursively
cm strip <INPUT> -b        # Remove blank lines
cm strip <INPUT> -a        # Aggressive mode: maximum stripping
cm strip <INPUT> --minify  # Minify to single line where possible
cm strip <INPUT> --strip-attrs # Remove all attributes (#[...])
cm strip <INPUT> --strip-docs  # Remove documentation comments

# Examples:
cm strip src/main.rs --output main.stripped.rs
cm strip src/ -r --aggressive --backup
cm strip src/ --recursive --strip-docs --minify
cm strip src/main.rs --force --output src/main.rs

Sweep Commands (AI Debug Statement Cleanup) -- CLEAN UP

cm sweep                    # Display overview of sweep capabilities for cleaning AI debug statements
cm sweep scan              # Scan for println!, eprintln!, and dbg! statements
cm sweep sweep [options]   # Clean up debug statements with intelligent pattern recognition
cm sweep convert           # Convert debug prints to proper logging statements
cm sweep analyze           # Analyze debug statement patterns and statistics
cm sweep init              # Initialize sweep configuration file

# Sweep Options:
cm sweep sweep -n          # Dry run (show what would be removed)
cm sweep sweep -p          # Interactive mode with pattern memory learning
cm sweep sweep -y          # Auto-approve all removals
cm sweep sweep -i          # Interactive confirmation for each statement
cm sweep sweep --backup    # Create backup files before cleaning

# Examples:
cm sweep sweep -p          # Learn patterns and clean interactively
cm sweep sweep -y          # Quick cleanup of all AI debug statements
cm sweep analyze --top 20  # Show top 20 files with most debug statements

Map Commands -- WHERE AM I

cm map                     # Display overview of dependency visualization and analysis tools
cm map show                # Present interactive visual representation of project dependency tree
cm map analyze             # Perform comprehensive analysis of project structure and dependencies
cm map export <path>       # Save dependency map data to external file format for documentation
cm map path <from> <to>    # Show the specific dependency path connecting two specified components

Probe Commands (Intelligent Probe Suite Management)

cm probe flake [options]    # Detect flaky probes that pass/fail inconsistently across multiple runs
cm probe impact [options]   # Run only probes affected by recent Git changes for faster feedback
cm probe coverage [options] # Generate coverage reports with automatic backend detection
cm probe profile [options]  # Measure execution time of individual probes with optional flamegraphs
cm probe tag [options]      # Custom probe categorization and selective execution using tags
cm probe ci-gen [options]   # One-click generation of CI pipelines that integrate Cargo-Mate probe commands
cm probe env [options]      # Manage Docker containers for probe dependencies (databases, services, etc.)
cm probe replay [options]   # Deterministically replay failed probe runs from saved snapshots
cm probe order [options]    # Detect probe ordering dependencies by randomizing execution sequence
cm probe doc [options]      # Generate comprehensive markdown documentation of all probes

# Flaky Probe Detection
cm probe flake -i 30 -j 8 --threshold 95  # Run each probe 30 times with 8 parallel workers, fail if pass-rate below 95%

# Impact Analysis
cm probe impact --base origin/main --head HEAD  # Run only probes affected by recent changes

# Coverage Analysis
cm probe coverage --open --threshold 85.0  # Generate coverage report and open in browser, fail if below 85%

# Performance Profiling
cm probe profile --top 15 --flamegraph slow.svg  # Profile slowest 15 probes and generate flamegraph

# Tag-Based Filtering
cm probe tag slow network        # Run probes tagged with both "slow" AND "network"
cm probe tag --exclude flaky     # Run all probes except those tagged "flaky"
cm probe tag --list              # List all available tags

# CI Configuration Generation
cm probe ci-gen --platform github --coverage --flake-detect --profile > .github/workflows/ci.yml

# Docker Environment Management
cm probe env up && cm probe env run && cm probe env down  # Start services, run probes, cleanup

# Failure Reproduction
cm probe replay 2024-09-25T14:30:15Z  # Replay failed probe run deterministically

# Randomized Execution Order
cm probe order --random --repeat 3  # Detect ordering dependencies by randomizing sequence

# Documentation Generation
cm probe doc -o PROBES.md --include-private  # Generate comprehensive probe documentation

Mutiny Commands -- THIS IS STILL DUMB

cm mutiny                  # Display overview of override capabilities and current mutiny status
cm mutiny activate <reason> # Enable mutiny mode to bypass cargo restrictions for specified reason
cm mutiny deactivate       # Disable mutiny mode and restore normal cargo restrictions
cm mutiny allow-warnings   # Temporarily permit compilation warnings without stopping the build
cm mutiny skip-tests       # Bypass test execution during build process in mutiny mode
cm mutiny force            # Override safety checks and force execution of potentially dangerous operations
cm mutiny yolo             # Enable maximum risk mode that disables all safety checks for 30 minutes
cm mutiny status           # Display current status of mutiny mode and active overrides

Config Commands -- CONFIGURE YOUR SHIP

cm config                  # Display overview of all configuration options and current settings
cm config set <key> <val>  # Assign a specific value to a configuration key
cm config get <key>        # Retrieve the current value of a specific configuration key
cm config list             # Show all current configuration settings with their values
cm config init             # Create and initialize a new local configuration file for the project
cm config shortcut <name>  # Create a custom command shortcut for frequently used operations
cm config hook <type>      # Add an automated script that triggers on specific build events

Optimize Commands -- OPTIMIZE CM

cm optimize                # Display overview of optimization capabilities and current optimization settings
cm optimize aggressive     # Apply maximum performance optimizations with potential stability trade-offs
cm optimize balanced       # Implement moderate optimizations balancing performance and stability
cm optimize conservative   # Apply minimal optimizations prioritizing stability over performance
cm optimize custom         # Implement user-defined custom optimization configuration
cm optimize status         # Show current optimization settings and their impact on build performance
cm optimize recommendations # Analyze project and suggest optimal performance improvement strategies
cm optimize restore        # Revert all optimizations and restore original Cargo.toml configuration

Checklist Commands -- STAY FOCUSED AND TOUCH GRASS

cm checklist               # Show current checklist
cm checklist show          # Show current checklist
cm checklist list          # List all checklist items with numbers
cm checklist add <item>    # Add an item to the checklist
cm checklist done <items>  # Mark items as done (e.g., "1,2,3" or "1")
cm checklist clear [target] # Clear checklist items (default: "all", or "done")

WTF Commands (CargoMate AI - Pro only) -- ONLY WORKS 25% OF THE TIME

cm wtf                     # Show WTF overview
cm wtf ask <question>      # Ask CargoMate AI a question
cm wtf er [count]          # Send recent errors to CargoMate AI (default: 10)
cm wtf checklist [limit]   # Send recent checklist items to CargoMate AI (default: 10)
cm wtf list [limit]        # List recent conversations (default: 10)
cm wtf show <id>           # Show specific conversation by ID
cm wtf history [limit]     # Show conversation history (default: 10)

# Ollama Integration
cm wtf ollama enable <model> # Enable local Ollama integration (default: llama2)
cm wtf ollama disable        # Disable local Ollama integration
cm wtf ollama status         # Show current Ollama configuration
cm wtf ollama models         # List available Ollama models

Tool Commands -- TOOLS ARE JUST HELPER FILES / BASE FILES FOR YOU TO USE IF WANTED

cm tool                    # Show tool system overview
cm tool list               # List all available tools
cm tool help <name>        # Show help for a specific tool
cm tool run <name> [args]  # Run a specific tool

# Available Tools:
cm tool bench-diff --from <commit> --to <commit> --threshold <percent>
    # Compare benchmark results between commits

cm tool dep-audit --strict --check-security --licenses "MIT,Apache-2.0"
    # Audit dependencies for security and license issues

cm tool test-gen --file <path> --type <unit|integration|property>
    # Generate test boilerplate from Rust function signatures

DDR Commands (Dock Dock Rust - Parallel Build Orchestration) 🚧 UNDER DEVELOPMENT

cm ddr                     # Display overview of DDR parallel Docker-based Rust build capabilities
cm ddr build [options]     # Build Rust project using Docker containers with parallel orchestration
cm ddr build --target <target> # Cross-compile for specific target architecture
cm ddr build --jobs <num>  # Set maximum parallel build jobs (default: 16)
cm ddr build --image <img> # Use custom Docker image for builds
cm ddr build --profile <profile> # Build with specific profile (debug/release)

# DDR Build Options:
cm ddr build -n            # Dry run (show what would be built)
cm ddr build --verbose     # Verbose output with detailed Docker commands
cm ddr build --no-cache    # Disable Docker layer caching
cm ddr build --clean       # Clean build artifacts before building
cm ddr build --watch       # Watch mode (rebuild on changes)

# Examples:
cm ddr build --target x86_64-unknown-linux-gnu --target aarch64-unknown-linux-gnu
cm ddr build --jobs 32 --profile release
cm ddr build --image rust:1.70 --verbose

General Commands

cm register [--license-key <key>] [--status] [--remaining] # Register or validate Pro license
cm init                    # Set up and initialize cargo-mate for a new project with default configuration
cm install                 # Install cargo-mate shell integration for enhanced command-line experience
cm activate                # Enable cargo-mate shell integration to provide additional functionality
cm checklist               # Display comprehensive project status checklist with actionable items
cm history [<kind>] [<limit>] # Show historical record of commands with optional filtering and size limits
cm idea <idea_text>        # Submit an idea for Cargo Mate development
cm debug                      # Debug command counter status (for testing)
cm user                    # Show user information and license status
cm --help                  # Display comprehensive help information for all available commands
cm --version               # Show current version information for cargo-mate installation

Project Configuration (.cg)

[project]
name = "my-project"
default_journey = "build"
auto_checklist = true

[version]
auto_increment = true
increment_policy = "patch"

[shortcuts]
build = "build --release"
test = "test --all"

Global Configuration (~/.shipwreck/config.toml)

[ui]
colors = true
verbose = false

[performance]
parallel_jobs = 4
incremental = true

Some Examples

Development Workflow

# Save current state before major changes
cm anchor save "pre-refactor"

# Record your development workflow
cm journey record "dev-workflow"
cargo check
cargo test
cargo build --release
# Ctrl+D to stop recording

# Replay the workflow anytime
cm journey play "dev-workflow"

Performance Optimization

# Check optimization recommendations
cm optimize recommendations

# Apply balanced optimizations
cm optimize balanced

# Monitor build performance
cm tide show

Version Management

# Initialize with semantic versioning
cm version init 1.0.0

# Versions auto-increment on builds
cargo build  # 1.0.0 -> 1.0.1
cargo test   # 1.0.1 -> 1.0.2

# Manual version bump for releases
cm version increment minor  # 1.0.2 -> 1.1.0

🚢 Cargo Mate

• 🚢 Your project is a ship

• ⚓ Anchors save your position

• 🌊 Tide charts track the flow

• 🗺️ Maps show the territory

• 🏴‍☠️ Mutiny overrides the captain

• 📝 Captain's log records the journey

• 🚢 Auto-versioning keeps your ship on course

• 🚀 Build optimization gives you the wind in your sails

📄 License

This project is licensed

For more information, visit: cargo.do/license

🚀 Installation : CARGO INSTALL CARGO-MATE

Option 1: Quick & Dirty Installer (Recommended - Works Everywhere... in Theory)

curl -sSL https://get.cargo.do/mate | bash

✅ No compilation needed, auto-detects platform, handles all dependencies

Option 2: Control & Freaky (Direct Download - Choose Your Platform and Speed)

# Linux x86_64 (glibc)
wget https://get.cargo.do/linux-x86-64.tar.gz -O cargo-mate-linux-x86-64.tar.gz
tar -xzf cargo-mate-linux-x86-64.tar.gz
cd cargo-mate-linux-x86_64
sudo ./install.sh

# Linux x86_64 (musl)
wget https://get.cargo.do/linux-x86-64-musl.tar.gz -O cargo-mate-linux-x86-64-musl.tar.gz
tar -xzf cargo-mate-linux-x86-64-musl.tar.gz
cd cargo-mate-linux-x86_64-musl
sudo ./install.sh

# Linux ARM64 (glibc)
wget https://get.cargo.do/linux-arm64.tar.gz -O cargo-mate-linux-arm64.tar.gz
tar -xzf cargo-mate-linux-arm64.tar.gz
cd cargo-mate-linux-aarch64
sudo ./install.sh

# Linux ARM64 (musl)
wget https://get.cargo.do/linux-arm64-musl.tar.gz -O cargo-mate-linux-arm64-musl.tar.gz
tar -xzf cargo-mate-linux-arm64-musl.tar.gz
cd cargo-mate-linux-aarch64-musl
sudo ./install.sh

# macOS Intel (x86_64)
wget https://get.cargo.do/macos-x86-64.tar.gz -O cargo-mate-macos-x86-64.tar.gz
tar -xzf cargo-mate-macos-x86-64.tar.gz
cd cargo-mate-macos-x86_64
sudo ./install.sh

# macOS Apple Silicon (ARM64)
wget https://get.cargo.do/macos-arm64.tar.gz -O cargo-mate-macos-arm64.tar.gz
tar -xzf cargo-mate-macos-arm64.tar.gz
cd cargo-mate-macos-aarch64
sudo ./install.sh

# Windows x86_64
wget https://get.cargo.do/windows-x86-64.tar.gz -O cargo-mate-windows-x86-64.tar.gz
tar -xzf cargo-mate-windows-x86-64.tar.gz
cd cargo-mate-windows-x86_64
# Run install.ps1 in PowerShell as Administrator

# Windows i686
wget https://get.cargo.do/windows-i686.tar.gz -O cargo-mate-windows-i686.tar.gz
tar -xzf cargo-mate-windows-i686.tar.gz
cd cargo-mate-windows-i686
# Run install.ps1 in PowerShell as Administrator

# Universal ALL PLATFORMS AVAILABLE (most of the time contains all)
wget https://get.cargo.do/latest.tar.gz -O cargo-mate-latest.tar.gz
tar -xzf cargo-mate-latest-musl.tar.gz
cd cargo-mate-latest-musl
sudo ./install.sh

### Option 3: Natural & Confused (Requires Build Tools)
```bash
# Prerequisites: apt install build-essential (or equivalent)
cargo install cargo-mate
cm install && cm activate

⚠️ Note: 20+ minute build time. Requires C compiler/linker. If you get "linker cc not found", use Option 1 or 2 instead.

Troubleshooting

• "linker cc not found": Install build-essential first, or use the curl/wget installers

• "GLIBC_2.32 not found": Use the universal installer (Option 1) which auto-selects compatible version

• Behind firewall: Use Option 2 to download manually

No more shipwrecks in the sea of cargo errors!