# alpaca
[](https://github.com/leoshimo/cogni/actions/workflows/rust.yml)
Unix native interface for interacting with LLMs.
## Focus
`alpaca` brings language model scripting (prompting) into familiar Unix
environment by focusing on:
- Ergonomics and accessibility in Unix shell
- Composability and interop with other programs - including `alpaca` itself
- Ease of language model programming in both ad-hoc and repeatable manner
For example, designing for IO redirection (`stdin`, `stdout`) allows `alpaca` to
work with files, editor buffers, clipboards, syslogs, sockets, and many external
tools without bespoke integrations.
## Features
- Unix-minded Design (IO redirection, composability, interop)
- Ad-hoc Language Model Scripting
- Flexible input and output formats (Text, JSON, NDJSON, Transcript)
- Standalone binary - No Python required
- Repeatable Scripts via Templates
## Non-Features
- Interactive use - instead, invoke `alpaca` from within interactive environments (REPLs, emacs, etc)
## Installation
```sh
# Install from crates.io
$ cargo install alpaca
# From source
$ cargo install --path .
```
## Setup
`alpaca` talks to the [Ollama Cloud API](https://docs.ollama.com/cloud). It
expects an Ollama API Key (create one at
<https://ollama.com/settings/keys>) supplied via the `--apikey` option or more
conveniently the `OLLAMA_API_KEY` environment variable:
```sh
# in shell configuration
export OLLAMA_API_KEY=your-api-key
```
By default requests are sent to `https://ollama.com`. To target a different
host — for example a local Ollama server — set `OLLAMA_API_ENDPOINT`:
```sh
export OLLAMA_API_ENDPOINT=http://localhost:11434
```
Pick a model with `-m/--model` (default `gpt-oss:120b`). See
<https://ollama.com/library> for available model identifiers.
---
## Basic Usage
See `alpaca --help` for documentation
```sh
# Via stdin
$ echo "What is 50 + 50?" | alpaca
50 + 50 equals 100.
# Via file
$ echo "What is 50 + 50?" > input.txt
$ alpaca input.txt
50 + 50 equals 100.
# Via flags
# -s, --system <MSG> Sets system prompt (Always first)
# -a, --assistant <MSG> Appends assistant message
# -u, --user <MSG> Appends user message
$ alpaca --system "Solve the following math problem" --user "50 + 50"
50 + 50 equals 100.
# Via repetitions of same flags. Useful for few-shot prompting
$ alpaca --system "Solve the following math problem" \
-u "1 + 1" \
-a "2" \
-u "22 + 20" \
-a "42" \
-u "50 + 50"
100
# Via both flags and stdin. Flag messages come before stdin / file
$ echo "50 + 50" | alpaca --system "Solve the following math problem" \
-u "1 + 1" \
-a "2" \
-u "22 + 20" \
-a "42"
100
```
---
## Tour of alpaca
An gallery of examples to get the inspiration flowing
> :warning: `alpaca` uses the [Ollama Cloud API](https://docs.ollama.com/cloud), thus *any data fed into program will be sent to Ollama* (unless you point `OLLAMA_API_ENDPOINT` at a local server).
### In the Shell
```sh
# Creating Summary of Meeting Transcripts
$ cat meeting_saved_chat.txt \
| alpaca -s "Extract the links mentioned in this transcript, and provide a high level summary of the discussion points"
# Narrate Weather Summary
$ curl -s "wttr.in/?1" \
| alpaca -s "Summarize today's weather using the output. Respond in 1 short sentence." \
| say
# Create a ffmpeg cheatsheet from man page
$ man ffmpeg \
| alpaca -T 300 -s "Create a cheatsheet given a man page. Output should be in Markdown, and should be a set of example usages under headings." \
> cheatsheet.md
# Create a commit message for staged changes
$ git diff --staged \
| alpaca -s "Create a commit message for the given staged changes. Use conventional commit format. Answer in a single-line raw plaintext. Don't use markdown." \
| git commit -F -
```
### `alpaca_shell` - Example Interactive Shell as a Shell Script
As an example scripting with `alpaca` a "chat" interface is provided at `bin/alpaca_shell`.
It is a simple (~90 LOC) but a fun and illustrative toy:
```sh
$ ./bin/alpaca_shell
alpaca> what markdown files here?
+ ls *.md
README.md
alpaca> open it in text edit
+ open -a TextEdit README.md
alpaca> find all rust files in this directory. Open in text edit
+ open -a TextEdit $(find . -type f -iname '*.rs')
alpaca> pause music
+ osascript -e 'tell application "Music" to pause'
alpaca> in 3 secs, show a notif saying "Hey". Also say it
+ sleep 3 && osascript -e 'display notification "Hey"' && say "Hey"
alpaca> what safari tabs are open
+ osascript -e 'tell application "Safari" to get the name of every tab of every window & the URL of every tab of every window'
leoshimo/cogni: Unix native interface to LLMs, https://github.com/leoshimo/cogni
alpaca> look at readme, say a quick summary of it
+ cat README.md
[.. snip ..]
The README.md file is for a project named 'alpaca', which is a Unix native interface for interacting with large language models (LLMs)... [.. snip ..]
```
### In Emacs
Emacs can use `shell-command-on-region` to pipe buffer regions to `alpaca`.
For example, the following defines a command that plumbs region to `alpaca`, optionally replacing original contents:
```emacs-lisp
(defun leoshimo/alpaca-on-region (start end prompt replace)
"Run alpaca on region. Prefix arg means replace region, instead of separate output buffer"
(interactive "r\nsPrompt: \nP")
(shell-command-on-region start end
(format "alpaca -s \"%s\"" prompt)
nil replace))
(global-set-key (kbd "M-c") #'leoshimo/alpaca-on-region)
```
This binding is useful across a wide range of tasks, for example:
- Normalizing non-uniform text - e.g. unstructured logs to structured JSON events.
- Editing or organizing text semantically - e.g. rewording or grouping by category.
- Generating summary for an Org Agenda doc.
### In Vim
Vim can run external shell commands on entire buffer or visual selection to
power similar workflows possible from Emacs. See `h :!` in vim.
For example, given a bulleted list of fruits, it an be sorted by color by:
1. Selecting the list of fruits in visual mode
2. Type `:!alpaca -s "Sort this list by color"`
