Metadata-Version: 2.4
Name: ape-linux
Version: 0.5.0
Summary: AI for Linux commands
Project-URL: Homepage, https://github.com/sbalian/ape
Project-URL: Repository, https://github.com/sbalian/ape
Author-email: Seto Balian <seto.balian@gmail.com>
Maintainer-email: Seto Balian <seto.balian@gmail.com>
License: MIT License
License-File: LICENSE
Keywords: ai,anthropic,linux,llm,openai,pydantic-ai
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: pydantic-ai-slim[anthropic,google,groq,mistral,openai]>=1.104.0
Requires-Dist: pydantic>=2
Description-Content-Type: text/markdown

# Ape

Ape is an AI for Linux commands.

```sh
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:

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

Ape works with the following providers supported by [Pydantic AI](https://ai.pydantic.dev/models/): OpenAI, Anthropic, Google, Groq, and Mistral.

To install ([`uv`](https://docs.astral.sh/uv/getting-started/installation/) recommended):

```bash
uv tool install ape-linux
```

Next, choose a model with `APE_MODEL` in `provider:name` form (see the
[Pydantic AI docs](https://ai.pydantic.dev/models/) for the supported providers and
models) and set your provider API key in `APE_API_KEY`. Ape infers the provider from
the model name and passes this key straight to it, so `APE_API_KEY` must be a key for
that model's provider. Ape uses its own key variable rather than a provider's standard
one (like `OPENAI_API_KEY`), so setting it up for Ape doesn't affect other tools on
your system:

```bash
export APE_MODEL=openai:gpt-5.4-nano
export APE_API_KEY=key
```

Both are required.

To run:

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

Output:

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

Another example:

```bash
ape Delete all the .venv directories under projects/
```

Output:

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

If you ask for something that isn't a Linux command task:

```bash
ape Tell me about monkeys
```

Ape prints a short explanation to standard error and exits with status `2`.
Commands only ever go to standard output, so a refusal is never mistaken for one
(and won't run if you pipe Ape into a shell):

```text
ape: I can only help with Linux and Unix command-line tasks.
```

You can set the sampling temperature with the `APE_TEMPERATURE` environment
variable (default `0.2`). Some models — for example certain reasoning models —
reject a temperature; set `APE_TEMPERATURE=undefined` to send none at all and let
the model use its own default:

```bash
export APE_TEMPERATURE=0.7        # use a specific temperature
export APE_TEMPERATURE=undefined  # send no temperature at all
```

## 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), run
`ape-system-info`:

```bash
ape-system-info
```

Output (example):

```text
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
```

See also: [Gorilla](https://github.com/gorilla-llm)