ape-linux 0.4.0

AI for Linux commands

Ape

Ape is an AI for Linux commands.

ape "Find all the important PDF files in user/projects. An important PDF file has 'attention' in its name. Write the results to important_files.txt and then move it to Documents."

Output:

find ~/user/projects -type f -name "*attention*.pdf" > important_files.txt && mv important_files.txt ~/Documents/

Ape works with any provider supported by Pydantic AI — OpenAI, Anthropic, Google, Groq, Mistral and more.

To install (uv recommended):

uv tool install ape-linux

Next, set the API key for your provider using its standard environment variable. For example:

export OPENAI_API_KEY=key      # for OpenAI models
export ANTHROPIC_API_KEY=key   # for Anthropic models

To run:

ape "Create a symbolic link called win pointing to /mnt/c/Users/jdoe"

Output:

ln -s /mnt/c/Users/jdoe win

Another example:

ape "Delete all the .venv directories under projects/"

Output:

find projects/ -type d -name ".venv" -exec rm -rf {} +

If you try to ask something unrelated to Linux commands:

ape "Tell me about monkeys"

you should get:

echo "Please try again."

You can change the model using --model or -m. Models are specified in provider:name form. See here for the supported providers and models. For example:

ape "List the contents of the working directory with as much detail as possible" --model anthropic:claude-sonnet-4-5

The model is resolved as follows:

1. If --model/-m is given, that value is always used.
2. Otherwise, if the APE_MODEL environment variable is set, its value is used.
3. Otherwise, the default openai-chat:gpt-4.1 is used.

So you can set a personal default without passing --model every time:

export APE_MODEL=anthropic:claude-sonnet-4-5

Output:

ls -lha

System-aware suggestions

Ape automatically detects a few facts about your machine and adds them to the prompt so the suggested command is correct for your environment — for example BSD (macOS) vs GNU (Linux) flags, the right package manager (brew, apt, dnf, pacman, ...), and tools that are actually installed. It looks at:

• operating system and version (macOS version or Linux distribution),
• whether the userland is BSD or GNU,
• CPU architecture (e.g. arm64 vs x86_64),
• your shell ($SHELL),
• whether you are root,
• available package manager(s) and common tools (rg, fd, jq, docker, ...).

This is all gathered locally with the Python standard library and is best-effort: if anything can't be determined it is simply left out. No identifying information is collected or sent — never your username, hostname, working directory, or home path.

To see exactly what Ape detects and sends (without calling the model), use --system-info or -s:

ape --system-info

Output (example):

Operating system: Darwin
macOS version: 26.5
Userland: BSD (macOS) — prefer BSD-compatible flags
Architecture: arm64
Shell: /bin/zsh
Privileges: non-root (use sudo for privileged actions)
Package manager(s): brew
Available tools: rg, fd, jq, git, curl, docker, tar, rsync, sed, awk

Executing commands

If you pass --execute or -e, the tool will run the command for you after printing it! Be careful with this as LLMs often make mistakes:

ape "Who am I logged in as?"

Output:

whoami
jdoe

For more help:

ape --help

See also: Gorilla