saya-cli 0.3.2

saya discovers the schema, writes the SQL, shows it to you, and runs it read-only and bounded against PostgreSQL, MySQL, SQLite, DuckDB, or Snowflake.

Install

Prebuilt binaries for macOS (Apple Silicon + Intel), Linux, and Windows are on every release, with SHA256SUMS to verify them.

brew install databook-studio/tap/saya   # macOS / Linux
cargo binstall saya-cli                 # prebuilt binary, no compile
cargo install saya-cli                  # from source (builds DuckDB; takes a few minutes)

→ installation

Quick start

saya config init                          # starter config in your user config dir (init prints the path)
$EDITOR ~/.config/saya/connections.toml   # point the example profile at your database
export SAYA_ANALYTICS_PASSWORD='...'      # the profile references it; never commit it
saya config doctor                        # secrets resolve? provider reachable?
saya                                      # start the TUI

config init writes to your user config directory, which saya trusts. Pass --project to write a .saya/ pair for a repository instead — that layer is untrusted, so security-critical settings in it are ignored unless you pass --trust-project-config. config doctor names what is missing and exits non-zero when the setup cannot run a query, so a script can tell.

The starter config points at a local Ollama; edit [ai] in config.toml for OpenAI, Anthropic, Gemini, or any OpenAI-compatible gateway.

One-shot, no TUI:

saya ask "how many orders shipped last week?"
saya query --sql "SELECT count(*) FROM orders"

What you get

• 🖥️ A real terminal UI — bottom-pinned input, streaming answers, a / command popup with fuzzy matching, @table schema autocomplete, and copy-out with Ctrl+O / Ctrl+Y / Ctrl+B. (demo)
• 🛡️ You see the SQL before it runs — the exact statement appears in the approval prompt and the transcript. --approval-mode picks ask, read-only, or never.
• 🧠 Memory — tell saya what a table means once and later questions carry it. Facts are typed, bound to the schema shape they depend on, and go stale when a column they rest on changes. saya never confirms a fact by itself and never picks between contradictions. Off by default. → memory
• 🔌 Databases — PostgreSQL, MySQL, SQLite, DuckDB, Snowflake — and one question can span several connected databases at once, with results side by side. (demo)
• 🤖 Providers — Ollama, OpenAI, OpenAI-compatible gateways, Anthropic, Gemini.
• ⚙️ Scriptable — piped or non-TTY input runs headless with text, JSON, or NDJSON output, and typed exit codes.

Safety

saya is read-only in two layers. Every statement is parsed and rejected if it writes, and the database session itself is opened read-only — Postgres default_transaction_read_only, MySQL transaction_read_only, SQLite PRAGMA query_only, a read-only DuckDB open. Results are bounded by a row cap and byte budgets, and marked when truncated.

Secrets live in your environment or on disk as references, never inline in committed config. Resolved secrets, provider headers, and raw result rows are structurally excluded from saved sessions.

Neither layer can prove that an arbitrary database function is side-effect free, and Snowflake has no session read-only switch — so connect with a least-privilege, read-only database role. → SECURITY.md

Documentation

saya --help and /help in the TUI are generated from the code, so they are always current — start there for flags and commands. The guides cover the rest:

Development

cargo fmt --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked

The demo GIFs are generated with vhs from the docs/*.tape scripts; the live ones need SAYA_API_KEY and a reachable database.

See CONTRIBUTING.md. Apache-2.0 licensed.