Shell Completions

Updated on Oct 5, 2026

Shell completions let you press Tab to complete Forge commands, subcommands, and options. You manage them with frg shell, which can add completions to your shell profile, remove them, or print the completion script.

Prerequisites

Forge is installed and on your PATH. See Installation.
You run the command from a project that Forge is initialized in. The project must contain .forge/config/project.toml. frg shell stops with Configuration error: Required configuration not found when it can't find project configuration.
You can write to your shell profile file.

Supported shells

`<SHELL>` value	Profile that Forge edits
`bash`	`~/.bashrc`, or `~/.bash_profile`
`zsh`	`~/.zshrc`
`fish`	`~/.config/fish/config.fish`
`powershell`	Linux/macOS: `~/.config/powershell/Microsoft.PowerShell_profile.ps1` Windows: `Documents\PowerShell\Microsoft.PowerShell_profile.ps1`

Any other value fails with Unsupported shell: <name>. Supported shells: bash, zsh, fish, powershell.

Install completions

Go to a project that has Forge configuration.
Run the command for your shell:

bash

frg shell install bash
frg shell install zsh
frg shell install fish
frg shell install powershell

Restart the shell, or reload the profile (for example, source ~/.bashrc).
Type frg and press Tab to check that completions work.

When the profile file already exists, Forge backs it up with a timestamp before editing it. Then it adds the completion line.

Add the profile line manually

To see the exact change before Forge makes it, use --manual. Forge prints the profile path, the line to add, and the reload command. It doesn't change any files.

bash

frg shell install bash --manual

Example output (the path depends on your home directory):

text

Manual Installation Instructions

Add the following line to your shell profile:
 /home/you/.bashrc

# Forge CLI completions (added by frg shell install)
eval "$(frg shell generate bash)"

Then reload your shell configuration:
 source /home/you/.bashrc

The line Forge adds depends on the shell:

Shell	Profile line
Bash	`eval "$(frg shell generate bash)"`
Fish	`frg shell generate fish \| source`
PowerShell	`frg shell generate powershell \| Out-String \| Invoke-Expression`

For Zsh, run frg shell install zsh --manual to see the line.

Generate a completion script

frg shell generate <SHELL> writes the completion script to standard output and doesn't edit any profile. Use it to load completions for the current session only:

bash

source <(frg shell generate bash)

You can also use it to save the script for review or for your own profile management:

bash

frg shell generate zsh > frg-completions.zsh

The script lists the commands Forge can load when you generate it. That includes the built-in utility and workflow commands and any custom commands from your configuration. After you change command configuration, run frg config validate, then restart the shell or regenerate the script.

Remove completions

bash

frg shell uninstall bash

Replace bash with the shell to clean up. Forge removes the lines it added and keeps a timestamped backup of the profile. If there's nothing to remove, Forge prints Forge completions are not installed.

Command reference

Command	Description	Options
`frg shell install <SHELL>`	Install shell completions	`--manual`: show manual installation instructions instead of auto-installing `-q, --quiet`: suppress all output except errors
`frg shell uninstall <SHELL>`	Uninstall shell completions	`-q, --quiet`
`frg shell generate <SHELL>`	Generate completion script without installing	`-q, --quiet`

Troubleshooting

Configuration error: Required configuration not found

Cause: You ran frg shell in a directory with no Forge project configuration. The installed profile line runs frg shell generate every time a shell starts. So this also happens when a new terminal opens outside a configured project: completions don't load, and the error can appear at startup.

Solution:

For one-time setup, run frg shell install <SHELL> from a project that contains .forge/config/project.toml, or run frg config init first.
If your terminals usually open outside a Forge project, load a saved script instead of generating it at startup:

bash

cd ~/src/my-project # a project with Forge configuration
frg shell uninstall bash # remove the startup line, if you installed it
frg shell generate bash > ~/.forge-completions.bash
echo 'source ~/.forge-completions.bash' >> ~/.bashrc

Regenerate the file after you upgrade Forge or change command configuration.

Verify: Open a new terminal, type frg and press Tab.

Tab shows no Forge commands

Cause: The profile doesn't have the completion line, or the shell hasn't reloaded it yet.

Solution:

Confirm Forge runs: frg --version.
Check the profile for the line: grep "frg shell" ~/.bashrc. Use ~/.zshrc or ~/.config/fish/config.fish for other shells. In PowerShell, open the file at $PROFILE.
Restart the shell or reload the profile.

Completions are missing custom commands

Cause: Forge couldn't load your command configuration when it generated the script.

Solution:

Run frg config validate and fix the reported errors.
Restart the shell, or regenerate a saved script.

The profile can't be modified

Cause: Your user can't write to the profile file.

Solution:

Run frg shell install <SHELL> --manual to get the profile path and the line to add.
Add the line through your usual profile-management process.