So, lately I switch shell from zsh to fish.
If you’ve recently made the jump from Zsh to Fish Shell like me, you’ve probably noticed how snappy, modern, and out-of-the-box functional Fish is. But if you’re a Laravel developer, there’s a good chance you immediately hit one annoying speed bump: losing artisan auto-completion.
Back in Zsh with Oh My Zsh, typing ./artisan and hitting Tab gave you contextual autocomplete for every command, argument, and flag. Naturally, when switching to Fish Shell, you want that feature back.
Here’s how the built-in generator works, why it breaks in everyday workflows, and a simple shell wrapper script to fix it cleanly.
The Standard Approach (And Why It Falls Short)
Laravel includes a built-in command generator for shell completion script via Symfony's Console component. Generating a completion file for Fish is as simple as running:
artisan completion fish | tee ~/.config/fish/completions/artisan.fish
(Note: You can also source it dynamically, but dumping it straight to ~/.config/fish/completions/ ensures Fish autoloads it automatically on launch).
Once installed, Fish tries to offer tab completions for artisan. But here is the catch: the generated script binds completion exclusively to the exact command name artisan.
In everyday development, you rarely type artisan make:model. Instead, you type php artisan make:model or ./artisan make:model
Because Fish matches completions strictly by the command at the start of your prompt, typing php artisan won't trigger the generated completions at all.
The Solution: A Global artisan Wrapper
Rather than modifying complex completion scripts to parse php artisan sub-arguments, a much cleaner approach is to create a global launcher script named artisan inside your local path (~/.local/bin/).
This wrapper accomplishes two things:
- It allows you to run
artisandirectly from anywhere without prependingphp. - If you are NOT in Laravel root project, you will got a "'artisan' file not found".
- It perfectly aligns your terminal invocations with the exact command target expected by Fish’s completion script.
Step 1: Create the Launcher Script
Create a file named artisan inside ~/.local/bin/:
nano ~/.local/bin/artisan
Paste the following script:
#!/usr/bin/env bash
# 1. Check if the artisan file exists in the current working directory
if [ ! -f "artisan" ]; then
echo "Error: 'artisan' file not found in the current directory." >&2
exit 1
fi
# 2. Check if the 'php' executable is available in PATH
if ! command -v php >/dev/null 2>&1; then
echo "Error: 'php' command not found or not accessible." >&2
exit 1
fi
# 3. Hand off execution to PHP with all passed arguments
exec php artisan "$@"
Make the script executable:
chmod +x ~/.local/bin/artisan
(Ensure ~/.local/bin is present in your PATH inside ~/.config/fish/config.fish via fish_add_path ~/.local/bin).
Step 2: Generate Fish Completions
Now that artisan is a top-level executable in your terminal path, generate the Fish completion file using your new wrapper:
artisan completion fish > ~/.config/fish/completions/artisan.fish
Open a new terminal tab or run source ~/.config/fish/config.fish.
The Result
Navigate to any Laravel project directory and simply type:
artisan make:<Tab>
Fish will now list available generators, options, and commands with full autocomplete support, matching the seamless experience from Zsh.
Why exec matters here
Notice the use of exec php artisan "$@" at the end of the script. Using exec replaces the shell process with the PHP process directly rather than spawning a child process. This keeps memory footprints light and ensures signals (like Ctrl+C during long-running tasks like artisan serve or queue:listen) are forwarded cleanly to PHP.

Top comments (0)