Installation

Install Tracer on macOS, Linux, or Windows using cargo or from source

Prerequisites

Tracer requires the Rust toolchain. If you don’t have it installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, ensure ~/.cargo/bin is in your PATH.

Quick Install (Recommended)

Cargo Install

cargo install trace-tracker

The tracer binary will be installed to ~/.cargo/bin/.

Tracer uses bundled SQLite, so no external database dependencies are required.

Platform-Specific Instructions

macOS

Option 1: From Git (Current)

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install tracer
cargo install --git https://github.com/Abil-Shrestha/tracer

Option 2: Homebrew (Coming Soon)

brew tap Abil-Shrestha/tracer
brew install tracer

Linux

Ubuntu/Debian

# Install build dependencies
sudo apt update
sudo apt install build-essential pkg-config libssl-dev

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install tracer
cargo install --git https://github.com/Abil-Shrestha/tracer

Arch Linux (Coming Soon)

yay -S tracer-git

From Binary Release

# Download from releases
wget https://github.com/Abil-Shrestha/tracer/releases/latest/download/tracer-linux-amd64

# Make executable
chmod +x tracer-linux-amd64

# Move to PATH
sudo mv tracer-linux-amd64 /usr/local/bin/tracer

Windows

Option 1: From Source

# Install Rust from https://rustup.rs/

# Install tracer
cargo install --git https://github.com/Abil-Shrestha/tracer

Option 2: From Binary

1. Download the latest Windows release from GitHub Releases
2. Extract tracer.exe to a directory in your PATH
3. Or run directly:

.\tracer.exe --help

Windows requires Visual C++ build tools. Install from Visual Studio Downloads and select “Desktop development with C++”.

Verify Installation

After installation, verify Tracer is working correctly:

1. Check version

   tracer --version
   

   Should output: tracer 0.2.0

2. View help

   tracer --help
   

   Should display available commands and options.

3. Test initialization

   mkdir test-project
   cd test-project
   tracer init
   

   Should create .trace/bd.db and .trace/issues.jsonl

Updating Tracer

Cargo Install

cargo install trace-tracker --force

Uninstalling

To remove Tracer from your system:

cargo uninstall tracer

To also remove project databases, delete the .trace directories:

find . -name ".trace" -type d -exec rm -rf {} +

Troubleshooting

Command not found

Ensure ~/.cargo/bin is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"

Then reload your shell:

source ~/.bashrc  # or source ~/.zshrc

Build fails on Windows

Install Visual C++ build tools:

1. Download from Visual Studio Downloads
2. Run the installer
3. Select “Desktop development with C++”
4. Complete installation and retry cargo install

SQLite errors

Tracer uses bundled SQLite, so external dependencies aren’t needed. If you see SQLite errors:

# Clean and rebuild
cargo clean
cargo build --release

If the error persists, check that you have write permissions in the project directory.

Permission denied on Linux

If you get permission errors when installing to /usr/local/bin:

# Option 1: Use sudo
sudo mv tracer /usr/local/bin/

# Option 2: Install to user directory
mkdir -p ~/.local/bin
mv tracer ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

Development Installation

For contributing to Tracer or testing unreleased features:

# Clone repository
git clone https://github.com/Abil-Shrestha/tracer.git
cd tracer

# Build in debug mode
cargo build

# Run tests
cargo test

# Run from source (useful for development)
cargo run -- --help
cargo run -- init
cargo run -- create "Test issue"

# Build optimized release binary
cargo build --release

# Binary will be in target/release/tracer
./target/release/tracer --version

The development build includes debug symbols and is slower. Use cargo build --release for production use.

Binary Aliases

Tracer provides two binary names for convenience:

• tracer - Full command name
• tr - Short alias for faster typing

Both are identical and can be used interchangeably:

tracer ready
tr ready  # Same command

Next Steps

Quick Start

Initialize your first project and create issues

Introduction

Learn more about Tracer’s features and use cases