Shell Shim

Shell Shim

The shell shim makes the plain flutter run command launch the flutter-cli TUI automatically — no wrapper script, no alias to remember.

---

How it works

The shim places a thin flutter script earlier in your PATH than the real Flutter SDK. When you type flutter run, the shim intercepts it and delegates to flutter-cli run. All other Flutter commands (flutter build, flutter doctor, etc.) are passed through unchanged to the real flutter binary.

---

Install the shim

flutter-cli shim install

The installer:

1. Detects the real Flutter SDK location (which flutter).
2. Creates ~/.local/share/flutter-cli/shim/flutter.
3. Prepends ~/.local/share/flutter-cli/shim to PATH in your shell profile.

You'll be shown exactly what it will write before it does anything.

Shell-specific profile files

Shell	File modified
bash	~/.bashrc (Linux) / ~/.bash_profile (macOS)
zsh	~/.zshrc
fish	~/.config/fish/config.fish
Other	You'll be shown the export PATH=… line to add manually

Reload your shell (or open a new tab) after installing:

source ~/.bashrc   # bash
source ~/.zshrc    # zsh
exec fish          # fish

---

Verify

which flutter
# → /Users/you/.local/share/flutter-cli/shim/flutter

flutter run        # Opens the TUI dashboard
flutter build apk  # Passes through to the real Flutter

---

Remove the shim

flutter-cli shim uninstall

This removes the shim directory and the PATH line from your profile. Your shell goes back to using the real flutter directly.

---

Manual setup

If you prefer not to modify your profile automatically:

flutter-cli shim install --no-profile

Then add this line yourself wherever you manage PATH:

export PATH="$HOME/.local/share/flutter-cli/shim:$PATH"

---

FAQ

Does the shim affect flutter build, flutter doctor, etc.? No. Only flutter run is intercepted. Everything else is forwarded to the real flutter binary unchanged.

What if I have multiple Flutter SDK versions (FVM, asdf)? The shim calls the flutter that was on your PATH at install time. If you switch SDK versions, run flutter-cli shim install again to update the reference.