<img src="https://raw.githubusercontent.com/cyber-boost/cargo-mate/refs/heads/main/github.png" alt="Cargo Mate: Rust development companion" width="600">
# 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](#-quick-start)
- [Command Reference](#-command-reference)
- [Installation](#-installation)
- [Version Commands](#version-commands)
- [View Commands](#view-commands)
- [Log Commands](#captains-log-commands-natural-language-build-notes-with-automatic-tagging-and-search)
- [Journey Commands](#journey-commands)
- [Anchor Commands](#anchor-commands)
- [Tide Commands](#tide-commands)
- [Scrub Commands](#scrub-commands)
- [SCAT Commands](#scat-commands-source-code-obfuscation-tool-still-under-development)
- [Strip Commands](#strip-commands-code-cleaning--optimization)
- [Sweep Commands](#sweep-commands-ai-debug-statement-cleanup)
- [Map Commands](#map-commands)
- [Mutiny Commands](#mutiny-commands)
- [Config Commands](#config-commands)
- [Optimize Commands](#optimize-commands)
- [Checklist Commands](#checklist-commands)
- [WTF Commands](#wtf-commands-cargomate-ai---pro-only)
- [Tool Commands](#tool-commands)
- [DDR Commands](#ddr-commands-docker-dock-rust---parallel-build-orchestration--under-development)
- [General Commands](#general-commands)
- [Project Configuration (.cg)](#project-configuration-cg)
- [Global Configuration (~/.shipwreck/config.toml)](#global-configuration-shipwreckconfigtoml)
- [Examples](#some-examples)
- [License](#-license)
## 🚀 Installation
### Option 1: Quick & Dirty Installer (Recommended - Works Everywhere... in Theory)
```bash
✅ No compilation needed, auto-detects platform, handles all dependencies
### Option 2: Control & Freaky (Direct Download - Choose Your Platform and Speed)
```bash
# 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
### Version Commands
```bash
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
```bash
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.)
```bash
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
```bash
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
```bash
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
```bash
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
```
### 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
```bash
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)
```bash
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)
```bash
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
```bash
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
```
### Mutiny Commands
```bash
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
```bash
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
```bash
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
```bash
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)
```bash
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
```bash
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
```
### DDR Commands (Docker Dock Rust - Parallel Build Orchestration) 🚧 UNDER DEVELOPMENT
```bash
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
```bash
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)
```toml
[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)
```toml
[ui]
colors = true
verbose = false
[performance]
parallel_jobs = 4
incremental = true
```
## Some Examples
### Development Workflow
```bash
# 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
```bash
# Check optimization recommendations
cm optimize recommendations
# Apply balanced optimizations
cm optimize balanced
# Monitor build performance
cm tide show
```
### Version Management
```bash
# 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](https://cargo.do/license)
---
Built with ❤️ for the Rust community.
No more shipwrecks in the sea of cargo errors!
<img src="https://raw.githubusercontent.com/cyber-boost/cargo-mate/3ebf3ef2f9eb64ec41e343a34e90f3a62f84d506/banner.svg" alt="Cargo Mate: Rust development companion" width="600">