guanaco-cli

An interactive CLI built with the @earendil-works/pi-tui framework that connects to a local LLM via Ollama. Guanaco is a wild version of Llama. Designed as a small, dependency-light base you can expand on.

No trading, no MCP, no payments — just CLI ↔ Ollama.

Features

• ☑ CLI Interface: Interactive terminal chat with streaming output.
• /help, /clear, /model, and shell execution commands.
• ☑ Shell Execution: Run system commands directly using the ! prefix (e.g., !ls, !git status).
• ☑ Configurable timeout, model, and base URL.
• ☑ Tests for the Ollama client.

Prerequisites

1. Node.js 20+
2. Ollama running locally:

   # Install: https://ollama.com/download
   ollama serve            # starts the server on http://localhost:11434
   ollama pull llama3.2    # or pull a lightweight model like qwen2.5:0.5b

Setup

cp .env.example .env
npm install
npm run dev

For a production-style run:

npm run build
npm start

# Override the model from .env using a flag
npm start -- --model qwen2.5-coder:3b

# Or simply as a positional argument
npm start qwen2.5-coder:3b

Environment variables

Variable	Required	Default	Notes
OLLAMA_BASE_URL		http://localhost:11434	Ollama HTTP endpoint
OLLAMA_MODEL		llama3.2	Must be pulled. Overridable via --model flag or positional arg.
OLLAMA_TEMPERATURE		0.8	Overridable via --temperature flag
OLLAMA_TOP_P		0.9	Overridable via --top-p flag
OLLAMA_NUM_CTX		2048	Overridable via --num-ctx flag
SYSTEM_PROMPT		(unset)	Prepended to every prompt if set
REQUEST_TIMEOUT_MS		60000	Ollama request timeout
STREAM_ENABLED		1	Stream the reply incrementally
DEBUG		0	Set 1 for verbose logs to stderr

Commands

• /help — list commands
• /clear — clear the terminal screen
• /model <name> — switch the active model (e.g., /model qwen2.5:0.5b)
• !<command> — execute a shell command (e.g., !git status)
• /exit or /quit — quit the application

Any other text message is forwarded to the LLM.

Project layout

src/
  index.ts      # entry point + graceful shutdown
  config.ts     # env parsing & validation
  cli.ts        # interactive terminal interface using pi-tui
  ollama.ts     # local LLM client + tool-calling loop
  tools.ts      # tool registry and dispatcher
  util/log.ts   # debug() helper

Scripts

Script	Purpose
npm run dev	tsx watch with live reload
npm run build	TypeScript build to dist/
npm start	Run the compiled app from dist/
npm test	Run the Vitest suite
npm run lint	ESLint over src/ and tests/

License

MIT