Skip to content

Terminal UI and search ​

autorag search answers one question end to end and autorag tui hosts the same librarian interactively. This page covers both surfaces: the flags, the agent's tools, the two-phase search, the numbered-citation output contract, and how to steer a running search.

Searching from the CLI ​

autorag search "<query>" runs the librarian agent loop: it routes the query, retrieves candidate evidence, reads and verifies the sources, and prints a curated answer with numbered results. It requires a configured chat model and a reachable decision model (Jev, the jev config section); the command checks the decision model first and stops before searching when it cannot answer.

bash
autorag search "What are our primary Q3 deliverables?"

Flags ​

FlagMeaning
--top-k <n>Maximum curated results.
--scope <scope>Narrow retrieval to an opaque virtual-path scope.
--fast-thinking <lvl>Thinking level for the fast first answer.
--final-thinking <lvl>Thinking level for the verified final answer.
--permission-mode <m>Approval gate for file changes: full (the default for search), auto, or ask. See Permission modes.

Thinking levels are off, minimal, low, medium, high, xhigh, max. The two phases default to minimal (fast) and high (verification). Global flags such as --json, --debug, --config, --search-paths, --workspace, and --model-provider are accepted by every command; see Global flags.

autorag search has no terminal to ask on, so it defaults to full permission. An explicit --permission-mode, AUTORAG_PERMISSION_MODE, or config value still wins.

Exit codes ​

CodeMeaning
0A curated answer was produced.
1The search failed at runtime (retrieval, datasource, or model error).
2Usage or model-configuration error (empty query, no model, invalid flag).
3Decision model unavailable (decision-model-unavailable).

JSON output ​

With --json, progress lines and the answer are machine-readable:

  • Progress: one JSON object per line, {"type":"progress","text":"…"}.
  • Fast answer: {"type":"preliminary","response":{…}}.
  • Final answer: {"answer":"…","results":[{"number":1,"title":"…","summary":"…","source":"…","locations":[…]}]}.

--debug adds sessionId, query, searched, and diagnostics to the envelope, and per-result confidence and evidence (each excerpt with its line, page, or section). Without --debug the JSON carries only the answer and the numbered results.

The interactive terminal UI ​

autorag tui runs Pi's interactive mode hosted on the librarian. Pi owns the terminal UI, provider credentials and OAuth, model selection, session persistence, resume/fork/compaction, settings, and extension loading; AutoRAG registers its domain tools and runs the two-phase search in the same session. The model's progress notes, fast answer, and final answer are ordinary assistant messages.

bash
autorag tui

Pi host commands ​

These commands are available in-session:

CommandPurpose
/login, /logoutProvider credentials and OAuth.
/modelPick the model. Required before the first search when no model is configured.
/resume, /new, /treeResume, start, or branch sessions.
/compact, /settingsCompact context, edit settings.

Typing while a search runs ​

Input typed during a search behaves like Pi's own turns:

KeyEffect
EnterSteer the running search: a correction applied before its next model request, then verified.
Alt+EnterQueue a new question for after the current search answers.
EscStop the search.

Embedding controls ​

The footer shows the embedding backend state and re-probes it periodically. Ctrl+Shift+E starts or stops the local minsync serve daemon, and /embedding [on|off|toggle|status] does the same without a bound key. When minSync.embedder is a remote endpoint there is no local daemon to toggle. See Running the embedding daemon and TUI footer and the /embedding command.

Messenger bridges ​

FlagEffect
--telegramLoad the Telegram bridge so a paired Telegram chat can ask, steer, and read answers.
--whatsappControl the session from WhatsApp; pair once with /whatsapp.
--whatsapp-group <jid>With --whatsapp, answer only this WhatsApp group. Requires --whatsapp.
--discordControl the session from Discord; creates a session channel.

A bridged TUI has nobody to answer a terminal approval dialog, so it defaults to full permission unless overridden. A bridged session does not register the ask_user tool. See Messenger connections.

Agent tools ​

Every tool takes a short i argument: one line describing what the call checks, shown to the user as live progress. The host registers Pi's built-in read, bash, edit, write, grep, find, and ls, plus the AutoRAG tools below. Tools whose backend is disabled or unavailable for the host are not registered.

ToolArgumentsPurpose
bashcommandFilesystem discovery and document reading with real paths (ls, find, grep, cat); in local sessions it also performs user-requested file organization.
writepath, contentCreate or save a file in a local session.
editpath, old/new textUpdate or replace an existing file in a local session.
search_all_documentsquery, topK?, scope?, since?, until?Fan out across every configured retrieval method and merge/rank candidates.
semantic_search_local_docsquery, topK?, scope?MinSync semantic/vector retrieval over parsed mirrors.
search_datasource_<id>query, topK?, scope?, since?, until?One generated tool per configured datasource connection; searches only that connection.
jikji_findquery, topK?, first?Local discovery through Jikji answer packs.
everything_searchquery, alternatives?, regex?, matchCase?, matchPath?, wholeWord?, kind?, path?, sort?, offset?, maxResults?Windows-only file/folder name search over the configured roots.
fsearch_searchquery, alternatives?, regex?, matchCase?, matchPath?, kind?, path?, sort?, offset?, maxResults?macOS/Linux file/folder name search; falls back to a bounded filesystem walk.
load_datasource_skillnameLoad instructions for a configured datasource skill.
check_memoryqueryInspect evidence earlier searches found, similar past questions, and long-term insights.
scan_duplicate_documentsnoneRead-only dupey scan of configured local document roots.
convert_filesinputs, to, outputDir?, recursive?, quality?, overwrite?, skipExisting?, keepDates?Offline file conversion (Filee).
list_file_conversionsfrom?List known formats, or what one source format can become.
calculatoroperation, expression?, timeZone?, toTimeZone?, date?, datetime?, from?, to?, plus per-operation count fieldsExact arithmetic, date, and time-zone math.
manage_automationsaction, id?, automation?Create, list, change, delete, and test file-triggered automations.
web_searchquery, recency?, limit?, num_search_results?Public-internet search through the credential-free provider chain.
web_fetchurl, raw?Read a public http(s) URL as markdown/text.
jevstate, questions, confidence_threshold?Ask the Jev judgment model for calibrated probabilities.
ask_userquestion?, context?, options?, allowMultiple?, allowFreeform?, questions?Ask the user a question at the terminal. Terminal sessions only; see Asking you questions.

There is no separate lexical-search tool: BM25-style ranking runs inside MinSync and is reached through search_all_documents. There is no datasource fan-out tool — every configured connection gets its own search_datasource_<id> tool.

External MCP-server tools (mcp__*) are registered through Pi alongside these; they are not covered by the file-permission gate.

Two-phase search and query routing ​

A search is progressive. Before any model turn, Jev routes the question to one of four branches: local (the answer needs the user's files, chats, mail, or public web), organize (the user wants files moved, renamed, converted, or tidied), extra (answerable from the model's own knowledge or a non-organization tool task), or config (inspect or change AutoRAG's own settings). A non-local branch needs Jev confidence of at least 0.75, otherwise the run falls back to a full local search. See Jev routing and decisions.

A local search then runs in two phases:

  1. Fast answer. Baseline MinSync and Jikji retrieval is gathered up front; the model writes a complete, self-contained first answer from that evidence with minimal thinking, without calling local search, retrieval, datasource, or file-reading tools. The calculator, web_search / web_fetch, and ask_user tools are the named exceptions.
  2. Verification. Jev checks whether the fast answer needs follow-up; if so the run continues into a verification phase that re-checks, fills gaps, and finalizes with the configured final thinking level. A steer from the user always forces verification.

The other branches (organize, extra, config) skip the fast answer and verification and run one tool-capable turn.

Directory access boundaries ​

Local retrieval sources are absolute filesystem paths and may be read with bash after verifying the returned path. Datasource retrieval sources use slash-prefixed virtual identifiers such as /kakao/..., /mailcrawl/..., /slack/..., /discord/..., and /github/...; they are not OS paths and must never be passed to cd, cat, or other filesystem tools — search them through the connection's search_datasource_<id> tool.

The librarian may organize, create, and modify local files with bash/write/edit when the user asks, but never performs permanent, unrecoverable deletion: files are moved to the OS trash instead. In ask and auto permission modes, changes to existing files go through the approval gate. See Permission modes.

Progress and steering ​

While a search runs, the host shows a progress widget built from the run's routing, decomposition, per-source hit/failure counts, and model phases, and each tool call displays its i line. In the TUI, Enter steers the running search, Alt+Enter queues a follow-up, and Esc stops it. A steer is framed to the model as a correction of the running search, cuts in-flight retrieval short, and is restated to the verification phase. A steer that lands after verification's last request still gets one more verification turn.

Released under the Apache-2.0 license.