ell

A command-line interface for LLMs written in Bash.

Features

basic.webm

Basic usage of ell (webm, 1,6MiB)

• Ask LLMs from your terminal
• Pipe friendly
• Bring your terminal context to the LLMs and ask questions
• Chat with LLMs in your terminal
• Function calling and more supported via templates
• Sensitive information redaction (#14)

Requirements

To use ell, you need the following:

• bash-4.1 or later
• coreutils / OS X utilities and awk and sed
• curl (For sending HTTPS requests)
• util-linux (Not necessary if you don't use record mode. For script command to record terminal input and output)

Install

git clone --depth 1 https://github.com/simonmysun/ell.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}/ell"
echo 'export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/ell:$PATH"' >> ~/.bashrc

This clones the repository into ${XDG_DATA_HOME:-$HOME/.local/share}/ell (following the XDG Base Directory Specification) and adds it to your PATH. You may clone it anywhere you like; only the directory on your PATH matters.

Alternatively, if ~/.local/bin is already on your PATH (as it is on many modern distributions), you can leave the repository directory off your PATH and instead symlink the launcher into it:

mkdir -p ~/.local/bin
ln -s "${XDG_DATA_HOME:-$HOME/.local/share}/ell/ell" ~/.local/bin/ell

Link the ell launcher (not ell.sh): it resolves the symlink back to the clone so the bundled helpers, templates and plugins are always found.

Upgrading from an older install? The previous layout (git clone ... ~/.ellrc.d with configuration in ~/.ellrc) still works: ~/.ellrc is still read, and templates and plugins under ~/.ellrc.d are still picked up. No migration is required.

Windows

ell is a Bash program, so run it from a Bash environment such as Git Bash, MSYS2, Cygwin or WSL.

The ell command is a plain wrapper script (not a symbolic link), so it works even when git does not create symlinks on checkout — the default on Windows unless Developer Mode or administrator rights are available. No extra setup is required; clone the repository and add its directory to your PATH as shown above. You invoke it the same way, e.g. ell "your prompt".

Environment differences and limitations. The Bash environments differ in how faithfully they emulate a POSIX system, and a few features degrade accordingly:

• WSL behaves like Linux; everything works.
• MSYS2 and Cygwin provide a fairly complete POSIX layer (ACL-backed file permissions, real symbolic links, script(1)), so the whole feature set works.
• Git Bash is intentionally minimal. Over NTFS it cannot create genuinely group/world-writable files, so the config-file permission check in load_config (which refuses to source a world-writable .ellrc) and the chmod 600 on the temporary auth-header file cannot be enforced; it also lacks script(1) (record mode) and, by default, real symlinks. ell still runs, but on a multi-user machine treat these as security limitations — see Configuration → Windows for details and the safer alternatives (MSYS2 / WSL).

For the most complete experience on Windows, prefer WSL or MSYS2 over Git Bash.

Configuration

See Configuration.

Here's an example configuration to use gemini-1.5-flash from Google. You need to set these variables in your config file, ${XDG_CONFIG_HOME:-$HOME/.config}/ell/config (the legacy ~/.ellrc also still works):

ELL_API_STYLE=gemini
ELL_LLM_MODEL=gemini-1.5-flash
ELL_TEMPLATE=default-gemini
ELL_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELL_API_URL=https://generativelanguage.googleapis.com/v1beta/models/

Here's an example configuration to use gpt-4o-mini from OpenAI.

ELL_API_STYLE=openai
ELL_LLM_MODEL=gpt-4o-mini
ELL_TEMPLATE=default-openai
ELL_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELL_API_URL=https://api.openai.com/v1/chat/completions

Usage examples

Make sure you have configured correctly.

Ask a question:

ell "What is the capital of France?"

Specify a model and use a file as input:

ell -m gpt-4o -f user_prompt.txt

reading from stdin is also supported:

cat somecode.py | ell -f -

If you prefer add another piece of prompt instantly instead of adding it in the template:

(cat somecode.py; echo "Explain this code") | ell -f -

Record terminal input and output and use as context:

ell -r
# do random stuff
ell What does the error code mean?
ell How to fix it?

Run in interactive mode:

ell -i

In interactive mode, record mode is automatically enabled to allow you chat with context.

Specify a template and start in record mode and interactive mode:

ell -r -i -t ctf-gemini

or

ell -r -i -t ctf-openai

depends on which API you are using.

ctf.webm

Example application of a capture the flag game (webm, 2.6MiB)

Writing Templates

See Templates.

Note that the use of the plugin support of LLM providers in ell is made with templates.

Styling

See Styling.

Plugins

See Plugins.

The term "Plugin" here means a script that can be called by ell. It can be used to extend ell's functionality. The plugins supported by LLM providers is not included here. Please refer to Templates.

Backends

See Backends.

A backend adapts ell to an LLM API "style" (selected with --api-style / ELL_API_STYLE). OpenAI and Gemini are supported out of the box, and you can add your own.

Architecture

See Architecture for how ell is put together: the startup sequence, configuration precedence, the request pipeline and its four hook stages, backends, and record mode.

Risks to consider

See Risks Consideration.

Q&A

• Q: Why is it called "ell"?

• A: "ell" is a combination of shell and LLM. It is a shell script to use LLM backends. "shellm" was once considered, but it was dropped because it could be misunderstood as "she llm". "ell" is shorter, easy to type and easy to remember. It does not conflict with any active software. Note that the name "shell" of shell scripts is because it is the outer layer of the operating system exposed to the user. It doesn't indicate that it is a CLI or GUI. Unfortunately it cannot be shortened to "L" which has the same pronunciation because that would conflict with too many things.

• Q: Why is it written in Bash?

• A: Because Bash is the most common shell on Unix-like systems and there is just no need to use a more complex language for this.

• Q: What is the difference between ell and other similar projects?

• A: ell is written in almost pure Bash, which makes it very lightweight and easy to install. It is also very easy to extend and modify. It is pipe-friendly, which means it is designed to be used in combination with other tools.

Similar Projects

• https://github.com/kardolus/chatgpt-cli - A CLI for ChatGPT written in Go.
• https://github.com/kharvd/gpt-cli A CLI for various LLM backends written in Python.
• https://github.com/JohannLai/gptcli A CLI for OpenAI LLMs written in TypeScript.
• https://github.com/x-cmd/x-cmd A huge collection of various tools which includes a CLI for LLM APIs. The project is written in POSIX bash and awk.
• https://github.com/llimllib/gpt-bash-cli A CLI for OpenAI API that saves the requests and responses into a database. It also uses the system keyring to store the API key, which is a lot more secure. This project is also written in bash.
• https://github.com/charmbracelet/mods A CLI tool to talk to LLMs written in Go. It has rich features in conversation management.
• https://github.com/hiquest/nicechat A CLI chat interface for OpenAI models, written in Node.js.
• https://github.com/closedloop-technologies/autocomplete-sh A CLI for LLM which uses completion to interact with users. It also acquires several history operations to provide better suggestions, also written in bash.
• https://github.com/plandex-ai/plandex A CLI tool to develop AI-integrated workflow, written in Go.
• https://github.com/simonw/llm A CLI tool for in-depth manipulation of LLMs, written in Python.
• https://github.com/sigoden/aichat A CLI tool talks to various LLM providers, written in Rust.
• https://github.com/npiv/chatblade A CLI Swiss Army Knife for ChatGPT, written in python

Testing

Run the whole suite on your host with bash tests/entry.sh, or across the supported Bash versions in Docker with bash tests/docker.sh. The tests are self-checking and dependency-free (the LLM backends are exercised offline via the ell_echo backend and file:// fixtures, so no network or API key is needed). See CONTRIBUTING.md for the layout and how to add a test.

Contributing

Contributions are welcome! Please open an issue or submit a pull request. See CONTRIBUTING.md for coding conventions and the test suite.

Changelog

See CHANGELOG.md for notable changes.

License

This project is licensed under the MIT License. See the LICENSE file for more details.