Installation¶

Homebrew (recommended)¶

The fastest way to install Trek on macOS is via Homebrew:

brew install bradleyfay/trek/trek

This installs the trek binary and keeps it up to date with brew upgrade.

Build from Source¶

Trek requires Rust 1.80 or later. If you do not have Rust installed, get it from rustup.rs.

git clone https://github.com/bradleyfay/trek.git
cd trek
cargo build --release

The compiled binary will be at target/release/trek. Copy it somewhere on your $PATH:

cp target/release/trek ~/.local/bin/trek

Shell Integration¶

Trek can integrate with your shell so that quitting Trek changes your shell session's working directory to wherever you were browsing. This is one of the most useful features for day-to-day use.

Run the installer once:

trek --install-shell

Then reload your shell config:

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

What the `m` function does¶

After installation, a shell function named m is added to your shell config. When you run m:

Trek launches in the current directory
You navigate normally
When you quit (q), your shell session cds to the directory Trek had open at exit

This means Trek acts as a navigation tool for your shell, not just a file viewer. You can use m as a replacement for cd when you are not sure exactly where you want to go.

Note

The underlying trek binary still works independently. m is a convenience wrapper — you are not required to use it.

Optional Dependencies¶

These tools are not required but enhance certain preview pane features when present:

Tool	Purpose	Install (macOS)
`chafa`	Inline image rendering — renders raster images as Unicode block characters or sixels in the preview pane	`brew install chafa`
`pdfinfo` (poppler-utils)	Full document metadata for PDF files	`brew install poppler`

Trek detects both tools at runtime. If either is absent, it falls back gracefully and shows a short install hint in the preview pane.

Verify the Installation¶

Run Trek directly to confirm it is working:

trek

Trek should open in the current directory with a three-pane layout. Press q to quit.