A simple but full-featured CLI for chatting with LLMs, written in TypeScript.
Thanks to Justin Bennett for the script that inspired this.
And it's easy to add more.
Equations render as images in Ghostty and Kitty, with raw TeX elsewhere. Try
npm run math-demo for examples.
Use -i / --image with a local file path or an HTTP(S) URL. Repeat the flag to attach
multiple images in order:
ai -i first.png --image second.jpg 'Compare these images'
ai -r -i third.webp 'How does this compare?'Local files support PNG, JPEG, GIF, and WebP on all platforms. On macOS, -i clipboard
reads an image from the clipboard. Image input works with OpenAI, Anthropic, and Gemini chat
models. Image generation models currently accept text prompts only.
Local HEIC/HEIF files are automatically converted to JPEG using macOS's sips, preserving
the original file. If sips is unavailable, convert the image to JPEG or PNG first. Images
are not resized before sending.
GPT image inputs use high detail. Requests are checked against each provider's byte limits
before sending, including base64 encoding, prompt text, and any image history sent in that
request: OpenAI 512 MB, Claude 32 MB (also 10 MB per base64 image), and Gemini 20 MB.
Oversized inputs produce an error; compress the images or shorten the chat to retry. OpenAI
and Claude send HTTP(S) image URLs as references, so the remote image bytes are checked by
the provider. Gemini downloads URL images and includes their base64 bytes in the request
check.
https://gist.github.com/david-crespo/a2bf06be5db310db967b2e35f6140da2
No streaming responses (yet).
Keys go in ~/.config/llm-cli/config.toml (or $XDG_CONFIG_HOME/llm-cli/config.toml),
grouped into profiles so you can keep separate keys, like personal and work. Run
ai profiles to create the file from a template (readable only by you) and to see where
each key will come from. Profiles are optional: if you already set keys with env vars, that
still works.
default_profile = "personal"
[profiles.personal]
anthropic = "sk-ant-..."
openai = "sk-..."
google = "..."
[profiles.work]
anthropic = "sk-ant-..."Pick a profile with --profile work or LLM_CLI_PROFILE=work. Otherwise, a new chat uses
default_profile, else the profile named default, else the only profile if there's just
one. With several profiles and none of those, you have to pick one. ai -r uses the profile
the chat was started with, so a reply bills the same account.
A provider missing from the profile falls back to its env var: ANTHROPIC_API_KEY,
OPENAI_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY. With no config file, the env
vars are all you need.
- Node 24 or later (essential)
gh(GitHub CLI, optional)- Only needed if you want to upload chats as GitHub gists
- You'll need to be logged in
(
gh auth login)
I plan to publish this to npm so it can be installed with npm install -g. Until then,
clone the repo, then run npm install and npm link in it. That puts ai on your PATH,
running src/main.ts from the repo with node through its shebang line, so changes to the
code take effect right away. You could also run it with node path/to/src/main.ts.
This is mostly for me (though I'd be thrilled if people find it useful), so I'm not really interested in changes that make this tool more general-purpose unless a) I want to use them, b) they don't make the interface any more complicated. The open issues include features I'd be interested in adding.