bilu

✨ Natural language to shell commands using AI ✨

What is this? • Installation • Usage • Contributing

What is this?

bilu is a lightweight, focused CLI tool that converts natural language into shell commands using Large Language Models (LLMs) like GPT-5. Unlike comprehensive agentic development tools like Claude Code or Cursor, bilu has a simple, singular purpose: helping you write shell commands faster, without switching context.

bilu is not a replacement for comprehensive agentic development tools -- it is simple tool that excels at one thing. Consider it the terminal equivalent of quickly searching "how do I..." and getting an immediately runnable answer.

After a response is generated, you can edit it before pressing enter to execute the command. This is useful if you want to add flags, or other modifications to the command.

Installation

1. One-line installer (Recommended)

You can install bilu with a single command:

curl -fsSL https://raw.githubusercontent.com/freddyjaoko/bilu/main/install.sh | sh

This will automatically detect your OS and architecture, download the correct compiled binary, and place it in your PATH.

2. Manual Installation from Releases

Go to the GitHub Releases page, download the binary for your platform, make it executable, and move it to your PATH:

chmod +x bilu-linux-x64
mv bilu-linux-x64 /usr/local/bin/bilu-cli

3. Build from Source

Clone the repo

git clone https://github.com/freddyjaoko/bilu.git
cd bilu

Install dependencies and build

Make sure you have Bun installed.

bun install
bun run build

This will produce the bilu-cli binary in the dist/ build output directory.

Make the binary executable and move it into your PATH

chmod +x dist/bilu-cli
mv dist/bilu-cli /usr/local/bin/bilu-cli

4. Configuration

bilu is configured through a single config.json file. The first time you run bilu, it will automatically launch an interactive setup wizard to help you configure your provider and API key.

Configuration File Location

The config.json file is located in a standard, platform-specific directory:

Linux: ~/.config/bilu/config.json
macOS: ~/Library/Preferences/bilu/config.json
Windows: %APPDATA%\\bilu\\config.json (e.g., C:\\Users\\<user>\\AppData\\Roaming\\bilu\\config.json)

Provider Types

You can configure bilu to use different AI providers. The supported types are "OpenAI", "Custom", "Claude", "Gemini", and "GitHub".

Below are examples for each provider type.

1. OpenAI (`type: "OpenAI"`)

This is the default configuration.

{
  "type": "OpenAI",
  "apiKey": "sk-your_openai_api_key",
  "model": "gpt-4o"
}

apiKey: Your OpenAI API key. If this is empty, bilu will use the OPENAI_API_KEY environment variable.

2. Claude (`type: "Claude"`)

Uses the native Anthropic API.

{
  "type": "Claude",
  "apiKey": "your-anthropic-api-key",
  "model": "claude-3-5-sonnet-20240620"
}

apiKey: Your Anthropic API key. If this is empty, bilu will use the ANTHROPIC_API_KEY environment variable.

3. Gemini (`type: "Gemini"`)

Uses the native Google Gemini API.

{
  "type": "Gemini",
  "apiKey": "your-google-api-key",
  "model": "gemini-1.5-flash"
}

apiKey: Your Google Gemini API key. If this is empty, bilu will use GEMINI_API_KEY or GOOGLE_API_KEY environment variables.

4. GitHub (`type: "GitHub"`)

Uses multiple free to use GitHub models.

{
  "type": "GitHub",
  "apiKey": "your-github-token",
  "model": "gpt-4o"
}

apiKey: Your GitHub token. If this is empty, bilu will use GITHUB_TOKEN or GITHUB_API_KEY environment variables.

5. Custom / Local Models (`type: "Custom"`)

This type is for any other OpenAI-compatible API endpoint, such as Ollama, LM Studio, or a third-party proxy service.

{
  "type": "Custom",
  "model": "llama3",
  "baseURL": "http://localhost:11434/v1",
  "apiKey": "ollama"
}

model: The name of the model you want to use (e.g., "llama3").
baseURL: The API endpoint for the service.
apiKey: An API key, if required by the service. For local models like Ollama, this can often be a non-empty placeholder like "ollama".

Context Configuration (Optional)

bilu can include recent command history from your shell to provide better context for command generation. This feature is disabled by default but can be enabled. When enabled, bilu includes the raw last N lines from your shell history (e.g., bash, zsh, fish), preserving any extra metadata your shell records:

{
  "type": "OpenAI",
  "apiKey": "sk-your_api_key",
  "model": "gpt-4o",
  "context": {
    "enabled": true,
    "maxHistoryCommands": 10
  }
}

enabled: Whether to include command history context (default: false)
maxHistoryCommands: Number of recent commands to include (default: 10) When enabled, bilu automatically detects and parses history from bash, zsh, and fish shells.

Notes on history scanning performance

Chunk size unit: When scanning shell history files, bilu reads from the end of the file in fixed-size chunks of 64 KiB. This is not currently configurable but can be made if desired.

Windows notes

History detection: On Windows, bilu searches for PowerShell PSReadLine history at:
- %APPDATA%\Microsoft\Windows\PowerShell\PSReadLine\ConsoleHost_history.txt (Windows PowerShell 5.x)
- %APPDATA%\Microsoft\PowerShell\PSReadLine\ConsoleHost_history.txt (PowerShell 7+) If not found, it falls back to Unix-like history files that may exist when using Git Bash/MSYS/Cygwin (e.g., .bash_history, .zsh_history).
Directory listing: On Windows, directory listing uses dir /b; on Linux/macOS it uses ls.

Clipboard Integration

bilu can automatically copy generated commands to your system clipboard:

{
  "type": "OpenAI",
  "apiKey": "sk-your_api_key",
  "model": "gpt-4o",
  "clipboard": true
}

clipboard: Whether to automatically copy generated commands to clipboard (default: false)

When enabled, every command generated by bilu is automatically copied to your system clipboard, making it easy to paste commands elsewhere. The clipboard integration works cross-platform:

macOS: Uses pbcopy
Windows: Uses clip
Linux: Uses xclip or xsel (falls back to xsel if xclip is not available)

Note: On Linux, you'll need either xclip or xsel installed for clipboard functionality to work.

5. Configure the `bilu` helper function

This function lets you type bilu <description> and get an editable command preloaded in your shell.

zsh

# ~/.zshrc

bilu() {
  local cmd
  cmd="$(bilu-cli "$@")" || return
  vared -p "" -c cmd
  print -s -- "$cmd"   # add to history
  eval "$cmd"
}

After editing ~/.zshrc, reload it:

source ~/.zshrc

bash

bilu() {
  local cmd
  cmd="$(bilu-cli "$@")" || return
  # requires interactive shell and Bash 4+
  read -e -i "$cmd" -p "" cmd || return
  builtin history -s -- "$cmd"
  eval -- "$cmd"
}

Powershell / Conhost / Windows Terminal

Note: This only applies to Windows with Powershell installed

To your Powershell profile, add this snippet

function bilu {
    param(
        [Parameter(ValueFromRemainingArguments=$true)]
        $args
    )
    $Source = '
    using System;
    using System.Runtime.InteropServices;

    public class ConsoleInjector {
        [StructLayout(LayoutKind.Sequential)]
        public struct KEY_EVENT_RECORD {
            public bool bKeyDown;
            public ushort wRepeatCount;
            public ushort wVirtualKeyCode;
            public ushort wVirtualScanCode;
            public char UnicodeChar;
            public uint dwControlKeyState;
        }

        [StructLayout(LayoutKind.Sequential)]
        public struct INPUT_RECORD {
            public ushort EventType;
            public KEY_EVENT_RECORD KeyEvent;
        }

        [DllImport("kernel32.dll", SetLastError = true)]
        public static extern IntPtr GetStdHandle(int nStdHandle);

        [DllImport("kernel32.dll", SetLastError = true)]
        public static extern bool WriteConsoleInput(
            IntPtr hConsoleInput,
            INPUT_RECORD[] lpBuffer,
            int nLength,
            out int lpNumberOfEventsWritten
        );

        const int STD_INPUT_HANDLE = -10;
        const ushort KEY_EVENT = 0x0001;

        public static void SendCommand(string text) {
            IntPtr hIn = GetStdHandle(STD_INPUT_HANDLE);
            var records = new INPUT_RECORD[text.Length];
            
            int i = 0;
            for (; i < text.Length; i++) {
                records[i].EventType = KEY_EVENT;
                records[i].KeyEvent.bKeyDown = true;
                records[i].KeyEvent.wRepeatCount = 1;
                records[i].KeyEvent.UnicodeChar = text[i];
            }

            int written;
            WriteConsoleInput(hIn, records, i, out written);
        }
    }';
    $cmd = bilu-cli @args;
    Add-Type -TypeDefinition $Source;
    [ConsoleInjector]::SendCommand($cmd)
}

This will work for Powershell terminals. To add this functionality to Conhost / Terminal, save this as bilu.bat and let it be accessible in PATH (you must do the Powershell step as well). For example,

:: assumes that ECHO ON and CHCP 437 is user preference
@ECHO OFF
CHCP 437 >NUL
POWERSHELL bilu %*
@ECHO ON

6. Updating & Uninstalling

Updating

To update bilu to the latest version, simply run the one-line installation command again:

curl -fsSL https://raw.githubusercontent.com/freddyjaoko/bilu/main/install.sh | sh

This will replace your bilu-cli binary with the newest compiled release. The installer automatically detects if your PATH and shell helper functions are already set up and will skip duplicating them.

Uninstalling

To completely remove bilu from your system:

Delete the binary:

rm -f /usr/local/bin/bilu-cli  # or ~/.local/bin/bilu-cli

Remove configuration & secrets (your API keys):
```
rm -rf ~/.config/bilu
```
Clean up shell profile: Open your shell profile (e.g. ~/.bashrc or ~/.zshrc) and delete the PATH export and helper function block added by the installer under the # Added by bilu installer comments. (For Fish users, also delete the function file: rm -f ~/.config/fish/functions/bilu.fish)

Usage

Once installed and configured:

bilu generate a new ssh key called bilu-key and add it to the ssh agent

You'll see the generated command in your shell's input line. Press Enter to run it, or edit it first. Executed commands will show up in your shell's history just like any other command.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a pull request.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
assets		assets
sample_configs		sample_configs
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
context.ts		context.ts
index.ts		index.ts
install.sh		install.sh
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

bilu

✨ Natural language to shell commands using AI ✨

What is this?

Installation

1. One-line installer (Recommended)

2. Manual Installation from Releases

3. Build from Source

Clone the repo

Install dependencies and build

Make the binary executable and move it into your PATH

4. Configuration

Configuration File Location

Provider Types

1. OpenAI (type: "OpenAI")

2. Claude (type: "Claude")

3. Gemini (type: "Gemini")

4. GitHub (type: "GitHub")

5. Custom / Local Models (type: "Custom")

Context Configuration (Optional)

Notes on history scanning performance

Windows notes

Clipboard Integration

5. Configure the bilu helper function

zsh

bash

Powershell / Conhost / Windows Terminal

6. Updating & Uninstalling

Updating

Uninstalling

Usage

License

Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. OpenAI (`type: "OpenAI"`)

2. Claude (`type: "Claude"`)

3. Gemini (`type: "Gemini"`)

4. GitHub (`type: "GitHub"`)

5. Custom / Local Models (`type: "Custom"`)

5. Configure the `bilu` helper function

Packages