Hailer

Hailer is a Python command-line package for chatting with your data. Ask questions about local CSV, Parquet, JSON or Excel files in plain English, and it explores the data and adds tables, charts and summaries to a live marimo notebook in your browser. You chat in the terminal; the notebook keeps the analysis and its Python code.

Documentation · Quickstart · Command reference

Quick start

You'll need:

• uv, which provides the uvx command. Install it, then reopen your terminal.
• An OpenAI API key for the default setup.
• A web browser.

These steps work in PowerShell on Windows and in a terminal on macOS or Linux. uvx downloads Hailer, its dependencies and a suitable Python version when needed. You do not need to clone this repository or install Docker.

1. Create a workspace and sign in

Run these commands in your terminal:

mkdir my-analysis
cd my-analysis
uvx hailer init
uvx hailer login openai

init creates your settings (hailer.toml), a starter notebook and a data/ folder. At the login prompt, paste your API key; input is hidden and the key is saved in your operating system's credential store. The starter settings use OpenAI with gpt-5.5.

For a company or another model endpoint, follow custom endpoint setup after init, using that provider's login command, then continue below.

2. Add your data

Copy the CSV, Parquet, JSON or Excel files you want to analyse into the data/ folder inside my-analysis. Any filenames work.

For a small example, save this as data/sales.csv in your workspace:

month,region,revenue
2026-01,North,1200
2026-01,South,900
2026-02,North,1500
2026-02,South,1100

3. Start chatting

From the same terminal, run:

uvx hailer

Hailer opens the notebook in your browser and starts the chat in your terminal. Keep the notebook tab open while you work; it provides the live session that runs the analysis.

Ask a question in the terminal, for example:

What data do I have? Summarise the columns and any missing values.

With the sample CSV, try:

Chart total revenue by month, split by region.

Tables and charts appear in the notebook. Type /exit to finish. To continue later, open a terminal in my-analysis and run uvx hailer again; it resumes your conversation and active notebook. Use /new for a fresh conversation, or /help to see the chat commands.

If startup fails, run uvx hailer doctor for checks and suggested fixes, or see Troubleshooting. A missing marimo server before your first session is expected: uvx hailer starts it for you.

Data and code: files are read locally, but your messages, code and notebook tool outputs (which can include data samples) go to the configured model endpoint. By default, notebook code runs with your account's file and network access. See Security and the optional Docker runtime for details.

Documentation

• Using Hailer: everyday workflow, notebooks and sessions, data and Excel.
• Configuration: models and endpoints, context, skills and prompts.
• Security: data handling, local and Docker runtimes.
• Help: installation and upgrades, troubleshooting, known limitations.

Development

git clone https://github.com/OpenAfterHours/hailer.git
cd hailer
uv sync --locked
uv run hailer login openai
uv run hailer
uv run pytest

Read the development guide for sample data and test details, and the release guide for the release process. Before changing the agent, providers, tools or conversation lifecycle, read docs/LEARNINGS.md, docs/INTERFACES.md and PLAN.md.

Preview the documentation:

uv run --locked --group docs zensical serve

See Maintaining the docs for build and publishing instructions.