Quickstart

This page gets you from a fresh install to a first answer. It assumes orrery is on your PATH (Install).

#1. Pick a model

Orrery needs a model provider. Two common choices:

A local model, no key. Install Ollama and pull a model:

ollama pull qwen3:4b
orrery providers add ollama --model qwen3:4b --use

A hosted model. Keep the key in an environment variable and save only its name:

export GEMINI_API_KEY=...
orrery providers add gemini --api-key '$GEMINI_API_KEY' --model gemini-2.5-flash --use

providers add asks the provider for its models before it saves anything. A refused key saves nothing.

What it saves is a few keys in ~/.orrery/config.toml. Writing them by hand does the same thing:

[providers]
default = "ollama"

[providers.ollama]
model = "qwen3:4b"

#2. Ask once

orrery run -p "Summarise README.md in three lines"

run -p takes one turn, prints the final text and exits. The session id and a resume command go to stderr, so stdout stays the answer.

#3. Open the TUI

orrery

Bare orrery opens the conversation in your terminal. If nothing is set up yet, it opens /providers first and walks you through it. See Your first session.

#Try it without any model

The fixture provider replays a recorded model stream from a .jsonl file. It needs no key and no network:

{"t":"started","id":"m1"}
{"t":"text-delta","text":"Hello from a fixture."}
{"t":"done","stop":"end-turn"}

orrery --provider fixture:./hello.jsonl run -p "hi"

#Next

• Your first session
• Providers and models