bai

A small AI shell-command helper. The name comes from the Chinese bai, associated with clarity and understanding.

A tiny CLI that translates a natural-language request into a shell command. You stay the approval gate — bai only proposes; the shell runs.

Landing page · API docs

$ bai list files in cwd sorted by date
ls -lt

The command is printed to stdout and copied to your clipboard (configurable), so you can paste, edit, or run it however you like. Or wire up the Alt-Enter keybinding to have bai rewrite your prompt buffer in place.

Installation

Arch Linux

Download the .pkg.tar.zst asset from the latest GitHub release, then install:

sudo pacman -U ./bai-*.pkg.tar.zst

Debian / Ubuntu

Download the .deb asset from the latest GitHub release, then install:

sudo dpkg -i ./bai_*.deb

If dpkg reports missing dependencies, finish with:

sudo apt-get install -f

Fedora / RPM

Download the .rpm asset from the latest GitHub release, then install:

sudo dnf install ./bai-*.rpm

On openSUSE, local unsigned RPMs need an explicit allowance:

sudo zypper install --allow-unsigned-rpm ./bai-*.rpm

TODO

• Make the provider layer flexible enough to support self-hosted or in-house LLM backends without bloating the default CLI UX.

From source

Requires Crystal and just.

git clone https://github.com/trans/bai
cd bai
just install                 # → /usr/local/bin/bai
PREFIX=~/.local just install # → ~/.local/bin/bai

Then either export your Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-...

Or drop it into your config directory:

mkdir -p ~/.config/bai
printf '%s\n' 'sk-ant-...' > ~/.config/bai/anthropic_api_key

Usage

bai <natural language query>

Examples:

bai count lines of Crystal code in src
bai find files modified in the last day
bai rename all jpg files in this folder to lowercase
bai show the largest 10 files under home

bai prints the proposed command (no trailing newline, so the clipboard content is ready to paste cleanly) and exits.

Flags

Environment variables

Environment variables override matching files in ~/.config/bai/ (or $XDG_CONFIG_HOME/bai/, or $BAI_CONFIG_DIR/ if you set that). For example:

~/.config/bai/provider
~/.config/bai/anthropic_api_key
~/.config/bai/openai_api_key
~/.config/bai/anthropic_model
~/.config/bai/openai_model
~/.config/bai/shell
~/.config/bai/clipboard
~/.config/bai/prompt_file
~/.config/bai/prompt.md

The mapping rule is simple: lowercase the env var name and drop the bai_ prefix when present. So BAI_PROVIDER becomes provider, and ANTHROPIC_API_KEY becomes anthropic_api_key.

prompt.md is the one special case: it is the actual prompt-addendum content file, not a string setting. By contrast, prompt_file contains a path if you want the addendum to live somewhere else.

Shell integration (Alt-Enter)

The keybinding lets you type a natural-language query straight at your prompt, hit Alt-Enter, and have it rewritten as the shell command — ready to edit or run.

fish — ~/.config/fish/config.fish:

function bai-replace
    set -l query (commandline)
    test -z "$query"; and return
    set -l result (bai -- $query)
    commandline -r -- $result
end
function fish_user_key_bindings
    bind \e\r bai-replace
end

bash — ~/.bashrc:

_bai_replace() {
    [[ -z "$READLINE_LINE" ]] && return
    READLINE_LINE="$(bai -- "$READLINE_LINE")"
    READLINE_POINT=${#READLINE_LINE}
}
bind -x '"\e\r": _bai_replace'

zsh — ~/.zshrc:

_bai_replace() {
    [[ -z "$BUFFER" ]] && return
    BUFFER="$(bai -- "$BUFFER")"
    CURSOR=${#BUFFER}
}
zle -N _bai_replace
bindkey '^[^M' _bai_replace

If Alt-Enter is already taken by your terminal or another binding, change the key sequence to taste (\cg, \e;, ^[^M, etc.).

Context sent to the model

Every call includes lightweight environment context so suggestions match your system:

OS: CachyOS
Kernel: 6.19.12-1-cachyos
Arch: x86_64
Shell: fish
CWD: /home/you/Projects/foo
HOME: /home/you
Editor: nvim

Inspect exactly what gets sent with bai --dry-run <query>.

If parent-shell detection is wrong because you are calling bai from an editor, launcher, or wrapper, force it explicitly:

bai --shell zsh list files modified today

Or set it persistently with BAI_SHELL / ~/.config/bai/shell.

Prompt addendum

Drop a file at ~/.config/bai/prompt.md (or anywhere, pointed to by BAI_PROMPT_FILE) to append your own preferences to the system prompt. Content is sent verbatim — what you write is what the model sees.

Example:

Prefer eza over ls, fd over find, rg over grep, bat over cat.
On this machine, pacman is the package manager.
Avoid sudo unless the request clearly requires it.

bai --dry-run will show your addendum in the rendered system prompt so you can verify it's loading.

Packaging

Local package build helpers:

just pkg-arch
just pkg-deb
just pkg-rpm

Strict and explain modes

Use --explain when you want a short reason for the generated command without breaking shell pipelines or command substitution:

bai --explain find large files

The command still goes to stdout. The explanation is printed to stderr.

Use --strict when you would rather have bai refuse an ambiguous request than guess:

bai --strict find the latest logs

In strict mode, bai exits with an error if the model cannot infer a safe, specific command confidently enough.

JSON output

Use --json when you want machine-readable output for wrappers, editors, or shell integration:

bai --json find large files

The JSON includes:

{
  "command": "find . -type f",
  "explanation": "Searches recursively for regular files.",
  "provider": "anthropic",
  "shell": "zsh",
  "strict": false
}

If you combine --json with --explain, the explanation stays in the JSON payload instead of being printed separately to stderr.

Development

just build       # release binary at bin/bai
just build-debug # debug build
just docs-api    # generate HTML API docs at docs/api
just pkg-src     # snapshot tracked files into pkg/bai-<version>.tar.gz
just pkg-arch    # build an Arch package in pkg/
just pkg-deb     # build Debian package artifacts in pkg/
just release-check # run spec + package checks before tagging a release
just run -- <query>
just test
just fmt
just check       # fmt --check + spec
just clean

License

MIT — see LICENSE.