Getting McFly Working on Ubuntu Server

McFly is a slick, Rust-powered shell history tool that supercharges your reverse search (Ctrl+R) with fuzzy matching, ranking, and a modern UI. I've been using it for almost 4 years now. I wrote about it's benefits in this tip on OneTipAWeek.com a while back.

I recently got a mini PC and decided to install some of the tools I normally use, like McFly. It's super easy to install McFly on an OS for a laptop/desktop, but on minimal environments like Ubuntu Server, it can silently fail even when it looks like it’s working. Ngl, I struggled lol. I thought it was just permissions, but it was a little more involved.

With that said, here's what you need to know to get it working on minimal environments like Ubuntu Server. I'm using Zsh, but if you're using a different shell, adjust accordingly.

What Works Out of the Box permalink

• McFly’s binary installs cleanly via cargo install
• The fuzzy search UI launches when you run mcfly search
• Zsh shell integration can be added with source <(mcfly init zsh)

What Doesn’t Work (at First) permalink

• McFly doesn’t actually save your history unless Zsh is correctly configured
• If you configure debugging for Mcfly, you might see messages like mcfly.zsh: Run mcfly add --exit 0 and assume it’s working. It's not.

Root Cause permalink

McFly doesn’t log every command live. Instead, it hooks into your shell via precmd_functions, flushes your shell history with fc -W. If you're curious what that command is, fc is the "fix command" built-in traditionally used to edit and re-run commands from your shell history.

It then ingests your shell’s history file (~/.zsh_history by default since I'm using Zsh).

If that file is empty or not being written to, McFly has nothing to work with.

This is especially common on minimal server setups like Ubuntu Server, where Zsh history settings aren’t configured at all.

The Fix: Cargo and some Config permalink

Install Rust & McFly permalink

McFly is written in Rust, so you’ll need Rust first. This is perfectly safe:

curl https://sh.rustup.rs -sSf | sh
source "$HOME/.cargo/env"

Then install McFly via Cargo:

cargo install mcfly --force

💡 Avoid the McFly install.sh script. While it might work fine on macOS or Ubuntu Desktop, it can silently fail on servers — skipping shell integration or writing files where your user doesn’t have permission. Cargo is predictable and reliable.

Configure Zsh Properly permalink

In your ~/.zshrc, add the following:

# Rust (if installed via rustup)
source "$HOME/.cargo/env"
export PATH="$HOME/.cargo/bin:$PATH"

# Zsh history settings (critical!)
export HISTFILE=~/.zsh_history
export HISTSIZE=10000
export SAVEHIST=10000
setopt INC_APPEND_HISTORY
setopt SHARE_HISTORY
setopt APPEND_HISTORY
setopt HIST_IGNORE_SPACE
setopt HIST_REDUCE_BLANKS

# McFly shell integration
source <(mcfly init zsh)

# Starship prompt (if used) — must come after McFly
eval "$(starship init zsh)"

If you're using Starship, why does its init script go after McFly's? Both Starship and McFly register Zsh hooks (precmd_functions). If Starship runs first, it can override McFly’s hooks unless you manually re-register them. By initializing Starship after McFly, both tools play nicely together.

Verify It Works permalink

1. Restart your shell:

   
   exec zsh
   

2. Run a test command:

   echo "hello mcfly"
   fc -W
   

3. Then check:

   tail ~/.zsh_history
   

   You should see echo "hello mcfly".

4. Finally, search via:

   mcfly search 
   

   or CTRL + R

   Start typing hello and you should see some results appear.

Debug Mode permalink

If you want to confirm McFly is running correctly, add this to your ~/.zshrc:

export MCFLY_DEBUG=1

You’ll start seeing lines like this in your terminal:

mcfly.zsh: Run mcfly add --exit 0

Note: this message only means the hook was triggered. It doesn’t guarantee the history file was written to or that the command was saved. Always confirm by checking that something was written to ~/.zsh_history.

Wrapping Up permalink

Here’s a quick checklist to make sure McFly actually works:

• Install with Cargo
  Reliable and builds from source

• Configure Zsh history
  Without it, McFly has nothing to save

• Use source <(mcfly init zsh)
  Hooks McFly into your shell prompt lifecycle

• Put Starship after McFly (if you're using it) Avoids overwriting McFly’s hooks

• Check ~/.zsh_history
  It must contain your recent commands for McFly to pick anything up

• Debug with MCFLY_DEBUG=1
  Helps you confirm if the hook is firing

Once it’s configured, McFly is the GOAT, even on a minimal Ubuntu Server. The key is making sure your shell is actually saving history before McFly tries to index it.

Want to connect? All my socials are at nickyt.online

Photo by Gabriel Heinzer on Unsplash