Christian Klotz
25cc5c7bf4
* docs(coding-agent): improve getting started documentation * docs(coding-agent): correct getting started details * docs(coding-agent): clarify SDK entry point * docs(coding-agent): restructure guides and references * docs(coding-agent): improve getting started guides * docs(coding-agent): refresh integration guides * docs(coding-agent): improve terminal and CLI guides * docs(coding-agent): refresh customisation guides * docs(coding-agent): clarify project trust terminology * docs(coding-agent): simplify customisation guidance * docs(coding-agent): improve runtime and reference guidance * Fix settings reference * feat(coding-agent): add Crowdin documentation sync * docs(coding-agent): separate CLI and slash command references * docs(coding-agent): correct compaction reference * docs(coding-agent): streamline package documentation * docs(coding-agent): split RPC reference documentation * Update configuration docs * Shorten config docs * docs(coding-agent): refine configuration references * docs(coding-agent): streamline settings reference * docs(coding-agent): clarify configuration reference * docs(coding-agent): clarify project trust exception * docs(coding-agent): simplify keybindings reference * docs(coding-agent): remove Crowdin integration * docs(coding-agent): turn themes reference into guide * docs(coding-agent): consolidate model and authentication docs * docs(tui): require Component.invalidate() (fixes #9358) * docs(coding-agent): document offline catalog behavior (fixes #8684) * docs(coding-agent): preserve established documentation routes * docs(coding-agent): reorganize documentation navigation * docs(coding-agent): correct audited behavior Clarify provider, session, local-model, Termux, TUI, SDK, debug, and extension behavior. Simplify the documentation audit to report only clear user-visible contradictions. * docs(coding-agent): fix broken documentation links
3.1 KiB
Configure shell commands
Pi starts a separate non-interactive shell process for each Bash command. Non-interactive Bash does not expand aliases by default and usually does not load the same startup files as an interactive terminal.
Use shellPath to choose the Bash executable and shellCommandPrefix to run setup before each command.
Understand which shell Pi uses
| Command source | Shell |
|---|---|
Model calls the built-in bash tool |
Pi's resolved Bash executable |
You enter !command or !!command |
The same resolved Bash executable |
Model calls the optional powershell tool |
PowerShell 7 (pwsh.exe) or Windows PowerShell |
| An extension provides or replaces a shell tool | The operations implemented by that extension |
Pi normally invokes Bash with bash -c. On Unix systems, it uses /bin/bash, then bash on PATH, and finally sh when Bash is unavailable. Native Windows first checks the configured path, then Git Bash, then bash.exe on PATH.
Choose a Bash executable
Set shellPath in ~/.pi/agent/settings.json when Pi should use a specific executable:
{
"shellPath": "~/.local/bin/bash"
}
On Windows, use forward slashes or escape backslashes:
{
"shellPath": "C:\\cygwin64\\bin\\bash.exe"
}
Run /reload after changing the setting. See Run Pi on Windows for the native Windows defaults.
Run setup before every Bash command
Set shellCommandPrefix to prepend shell setup to both the built-in bash tool and user-entered ! or !! commands:
{
"shellCommandPrefix": "export CI=1"
}
Pi joins the prefix and requested command with a newline. The prefix runs again for every command, so keep it fast and free of interactive prompts.
Enable Bash aliases
Store aliases needed by Pi in a Bash-compatible file instead of parsing an entire interactive shell configuration.
Create ~/.bash_aliases:
alias ll='ls -la'
alias gs='git status --short'
Then configure Pi to enable alias expansion and load the file:
{
"shellCommandPrefix": "shopt -s expand_aliases\nsource ~/.bash_aliases"
}
Run /reload, then verify the alias through Pi:
!ll
The command should produce the same listing as ls -la.
Aliases must use Bash-compatible syntax. Do not source an arbitrary .zshrc into Bash because zsh options, functions, and plugins may not parse or behave correctly there.
Troubleshooting
The prefix works for ! but not for an extension tool
shellCommandPrefix configures Pi's built-in Bash execution. An extension that replaces the bash tool or provides its own shell operations controls its own setup. Check that extension's documentation.
shopt is not found
Pi has fallen back to sh or shellPath points to a non-Bash shell. Install Bash or set shellPath to a Bash executable before using Bash-specific setup such as shopt.
A setup command waits for input
Remove interactive commands from shellCommandPrefix. The prefix runs in a non-interactive process before every Bash command.
For the complete setting definitions, see Shell settings.