asky-cli 0.4.15

asky is a command-line AI assistant with web search, local document Q&A, conversation history, and an optional XMPP remote-chat mode.

It runs as asky or ask. You give it a query, it gives you an answer.

What you need to get started

• Access to an OpenAI compatible LLM provider (OpenRouter, Gemini, OpenAI, Antrophic or a local model via LM Studio, Ollama, etc.)
• A search provider for web queries, Asky supports:
  • Local SearXNG instance.
  • Tavily (1000 free requests, per month).
  • Serper (2500 free requests, one time).

New here? Start with the Quick Start guide.

Features

• Multi-model support - define model aliases for any OpenAI-compatible API endpoint and switch between them with -m.
• Web search and tool calling - the model can search the web, fetch URLs, and use the current date to answer questions. Tool calls are visible in the output.
• Deep research mode - iterative retrieval across web sources and local documents, with a vector-indexed local corpus for semantic search.
• Document Q&A - point asky at a PDF, EPUB, or folder of files and ask questions about the content. See Document Q&A.
• Conversation history and sessions - every query is saved locally. Resume any previous conversation with -c, or use named sticky sessions with -ss.
• User memory - save facts across sessions. asky injects relevant memories into future queries automatically.
• Custom tools - expose any local CLI command as a tool the model can call.
• XMPP daemon mode - run asky --daemon to log into an XMPP account and accept queries over chat from any XMPP client app (phone, desktop, etc.). Includes voice transcription on macOS.
• Web Admin Console - authenticated browser interface for persona management, web collection review, and background job monitoring.
• Cross-platform system tray - on macOS, Linux, and Windows, daemon mode adds a tray icon for start/stop control and auto-start at login.
• Playwright browser plugin - fetches pages using a real browser, useful for sites that block standard HTTP clients.
• File prompts - load a prompt from a file with file://path/to/prompt.txt.
• Smart context management - summarizes old conversation turns in the background to stay within model context limits.

Installation

As a CLI tool

This is the typical way to install asky. It gets its own isolated environment managed by uv:

uv tool install asky-cli

Optional extras:

# iTerm2 terminal context integration (macOS)
uv tool install "asky-cli[iterm2]"

# XMPP daemon (text only)
uv tool install "asky-cli[xmpp]"

# Voice transcription (macOS, mlx-whisper)
uv tool install "asky-cli[mlx-whisper]"

# macOS full bundle: iterm2 + mlx-whisper + rumps + slixmpp
uv tool install "asky-cli[mac]"

# System tray icons (Linux/Windows)
uv tool install "asky-cli[tray]"

# Playwright browser plugin
uv tool install "asky-cli[playwright]"

From source:

uv tool install -e .

As a library

If you want to use asky programmatically in your own Python project (see Library Usage Guide):

uv pip install asky-cli

Basic Usage

# Basic query
asky what is the correct temperature for green tea

# Ask about a local document
asky -r path/to/report.pdf "What are the main conclusions?"

# Research mode - web sources
asky -r web "Compare the latest iPhone vs Samsung flagship specs"

# Continue from a previous query
asky -c "~1" explain more

# Persistent named session
asky -ss "Project X" "Let's plan the API structure"

# Use a specific model alias (defined in models.toml)
asky -m gf "Explain quantum entanglement"

# Copy final answer to clipboard
asky -cc "Write a regex to match email addresses"

# Pro-tip: Create a clipboard-first alias for command-only terminal assistance:
# alias al='asky -L -cc -sp "You are a CLI assistant. Answer briefly. When the user asks for a shell command, return only the command text. No markdown, no code fences, no explanation."'

# Run XMPP daemon in the background (menu bar on macOS if supported)
asky --daemon

# Run daemon attached to the terminal
asky --daemon --foreground

# Edit daemon settings interactively
asky --config daemon edit

# Add or edit model aliases
asky --config model add
asky --config model edit gf

# History, sessions, memory
asky history list 20
asky session list
asky memory list

Example output for a query that uses web search:

$ asky "What is the weather in Delft right now?"
Dispatching tool call: web_search with args {'q': 'weather Delft Netherlands'}
Dispatching tool call: get_url_content with args {'urls': [...]}

The weather in Delft, South Holland is currently 45°F, cloudy with showers.

Query completed in 3.88 seconds

Run asky --help for the full list of commands and flags.

Documentation

User guides

• Quick Start - install, configure, first query
• Configuration and Setup - TOML config files, API keys, model aliases, sessions
• Document Q&A - ask questions about local files
• Deep Research Mode (-r) - multi-source web and local document research
• User Memory & Elephant Mode (-em) - persistent cross-session memory
• XMPP Daemon Mode - remote access via XMPP chat, voice transcription
• Custom Tools - expose local CLI commands to the model
• Playwright Browser Plugin - browser-based page retrieval
• Plugin Runtime and Built-in Plugins - plugin system, persona tools, GUI server
• Troubleshooting - common problems and fixes

Developer / advanced

• Library Usage Guide - programmatic usage via asky.api
• Development Guide - project setup, auto-reload, contributing
• Research Evaluation - evaluating retrieval quality across models

Maintainer release flow: bump [project].version in pyproject.toml, push to main, and let the Publish package GitHub Actions workflow run the tests, upload dist/* to a GitHub Release, and publish the same artifacts to PyPI.