shell-buddy Installation, Usage and Configuration

shell-buddy turns natural language into command suggestions inside a native shell. Start a line with //, press Enter once to fill the command line, then press Enter again to execute. The command remains editable before execution and runs in the current shell.

The two-step flow here refers to ordinary Enter. With terminal shortcuts configured, there is also a path to accept and submit directly.

This guide targets v0.1.0, checked on 2026-10-24. Examples and limitations refer to that release, not to later changes on main.

Platforms and requirements

• Release packages: macOS Apple Silicon, macOS Intel, Linux x86_64 and Windows x86_64.
• Shells: Zsh 5.8+; Bash 5+; or PowerShell 7.4+ with PSReadLine 2.3.6+.
• The Bash bundled with macOS is too old. Install Bash 5+ separately or use a supported Zsh version.
• Release packages do not require Zig, Python or Node.js. Local models still require a separately prepared and running model service.

The initial packages are unsigned and not notarized. The installer verifies SHA256SUMS from the same release, but checksums do not replace a publisher signature. Download from the project repository, review the installer, and verify its source if the operating system raises a security warning. Installation documentation

Install v0.1.0

macOS and Linux

Download the pinned installer first. Review /tmp/shell-buddy-install.sh before running the second command:

curl -fsSL https://raw.githubusercontent.com/zhanbodev/shell-buddy/v0.1.0/install.sh -o /tmp/shell-buddy-install.sh
sh /tmp/shell-buddy-install.sh --version v0.1.0
export PATH="$HOME/.local/bin:$PATH"

The executable is installed to ~/.local/bin by default. The PATH assignment above affects only the current session. Add the appropriate assignment to your shell startup file for persistence, without duplicating an existing setting.

Windows

In PowerShell 7.4+, download the script and review the file named by $installer before running pwsh -File:

$installer = Join-Path ([IO.Path]::GetTempPath()) 'shell-buddy-install.ps1'
Invoke-WebRequest https://raw.githubusercontent.com/zhanbodev/shell-buddy/v0.1.0/install.ps1 -OutFile $installer
pwsh -File $installer -Version v0.1.0
$env:PATH = "$env:LOCALAPPDATA\Programs\ShellBuddy\bin;$env:PATH"

The default directory is %LOCALAPPDATA%\Programs\ShellBuddy\bin. This PATH assignment also affects only the current session; retain the directory in your user PATH if needed.

The installer requires no administrator privileges and also installs the project font by default. It does not modify PATH, shell startup files, terminal settings or model configuration. Installing the font does not enable the lizard icon by itself. Installer behavior

Integrate with the current shell

Run only the line matching your shell:

# Zsh
eval "$(shell-buddy init zsh)"

# Bash
eval "$(shell-buddy init bash)"

# PowerShell
shell-buddy init powershell | Out-String | Invoke-Expression

After confirming that the current session works, put its initialization line in ~/.zshrc, the startup file actually loaded by interactive Bash (usually ~/.bashrc), or PowerShell’s $PROFILE. Do not copy initialization lines for other shells.

The init commands with a shell name load integrations. The argument-free shell-buddy init command below opens the model setup wizard. Shell integration

Configure a local or cloud model

Run:

shell-buddy init

The wizard asks for a local or cloud profile, a Base URL, model name, API key and icon. API key input is hidden. Do not put real keys in shared command examples, screenshots or public configuration files.

The local template uses http://localhost:11434/v1. Its model name, YOUR_LOCAL_MODEL, is a placeholder that must be replaced by a model your service actually provides. The wizard does not install or download models, start a service or send a connectivity test request. Leave the key empty for a local service without authentication; pressing Enter when a key is already saved keeps it.

For a cloud profile, use the provider’s actual Base URL and model name. The implementation requires streaming /chat/completions, appends that endpoint to the Base URL and always sends reasoning_effort: "none". The service must accept those details; an “OpenAI-compatible” label alone does not establish compatibility.

Inspect or switch configured profiles with:

shell-buddy llm
shell-buddy llm local
shell-buddy llm cloud

The last two commands are alternatives for selecting a profile, not consecutive installation steps. Switching notifies active editors. A failed local service does not automatically fall back to cloud, or vice versa. Configuration reference

Check configuration and make a first request

Inspect the configuration and integration state the program recognizes:

shell-buddy doctor

doctor does not verify model connectivity. An explicit generation test can check the next step; this example targets Zsh:

shell-buddy suggest --shell zsh --intent 'Find large files in the current directory' --generate --timings

For Bash or PowerShell, replace zsh with bash or powershell. This command prints a suggestion without executing it or writing to the accepted-command cache. It sends a generation request to the selected model service.

Then start a line with // and describe an intention in a shell with the integration loaded. Once the suggestion is complete, press Enter to fill the command line. Check paths, options and scope before pressing Enter again to run it. Command reference

Configuration files, credentials and cache

Default configuration locations:

• macOS/Linux: $XDG_CONFIG_HOME/shell-buddy/config.json, or ~/.config/shell-buddy/config.json when the XDG path is unset.
• Windows: %USERPROFILE%\.config\shell-buddy\config.json; XDG_CONFIG_HOME is also supported.
• SHELL_BUDDY_CONFIG overrides the configuration path. credentials.json and state.json follow the actual configuration directory.

Default cache locations:

• macOS/Linux: $XDG_CACHE_HOME/shell-buddy/cache.json, defaulting to ~/.cache/shell-buddy/cache.json.
• Windows: %LOCALAPPDATA%\shell-buddy\cache.json.
• SHELL_BUDDY_CACHE overrides the cache path.

Credentials are stored in plaintext files, not an operating-system keychain. POSIX uses a dedicated directory with 0700 permissions and configuration/credential files with 0600 permissions. Windows uses a current-user ACL. Do not commit the configuration directory to a repository or shared drive.

The api_key_env field takes an environment-variable name, not the key itself. That variable takes priority over the saved key. An explicitly configured variable that is empty or invalid causes an error instead of a silent fallback to the saved key.

The cache holds at most 256 accepted commands, separated by intention, operating system, shell, working directory, model configuration and output budget. Acceptance means a command was filled into the input line, not that it ran or succeeded. Clear the cache with:

shell-buddy cache-clear

Paths, credentials and caching

Troubleshooting and boundaries

• shell-buddy is not found: check that its installation directory is in the current session’s PATH, then reload the shell integration.
• // does not enter the suggestion flow: check the shell version, matching initialization line and, for PowerShell, the PSReadLine version.
• No model response: check the selected profile, running service, model name, API key and supported request parameters. The default request timeout is 8,000 ms. A successful doctor check is not a successful model test.
• Response settings: input debounce defaults to 150 ms; max_tokens defaults to 2,048 and permits 1–32,768. The final command must be a single line of at most 4,096 bytes. Incomplete or failed streamed output cannot be accepted.
• Broken icons: v0.1.0 accepts only star and lizard for icon, defaulting to star (✦). The lizard requires a terminal font that can display U+F5000. This version has no setting to disable animations or hide the icon entirely.
• Working without a model: existing cache entries and explicit local rules can still match. They do not provide general-purpose offline natural-language generation.

Model requests include the intention, operating system, shell type and current directory. Requesting another candidate also includes existing candidates. The program does not read and upload project files, directory listings, shell history or other environment-variable values. With a cloud model, however, descriptions and paths still go to the selected service. Do not put secrets or information inappropriate for that service into an intention.

shell-buddy has no security sandbox or semantic safety review for dangerous commands. Two presses of Enter are an interaction designed for human inspection, not a safety certification. Understand deletion, overwrite, permission and remote-operation commands before executing them. This is part of keeping engineering judgment when using AI.

These settings and limitations are grounded in the v0.1.0 reference and command-generation implementation.