Command-line reference

Every discovery command and its options, the JSON output, exit codes and citation formats - for the curious, for power users, and for checking what your agent ran.

#Who this is for

You never have to type these commands: your AI agent runs them, and every one shows up on the Agent log screen. This page is for checking what an agent did, for running a quick check yourself (discovery doctor is handy), and for power users.

The tool installs from the Start Up screen (Install command-line tool). On a Mac it is ~/.local/bin/discovery; on Windows %LOCALAPPDATA%\Discovery Engine\bin\discovery.cmd. If it isn't on your PATH, run it by that full path.

Every command has --help with examples:

discovery --help
discovery search --help

discovery agent-guide prints the complete guide for AI agents (the same text the app writes to AGENTS.md and CLAUDE.md).

#How the tool behaves

• It shares the app's state. When the app is running, the command talks to its engine. When the app isn't running, the command opens the case itself.
• It works on the current case (the one opened last in the app) unless you name another with --case.
• It shows the case as written: real names, each file's real name and path, a file:// link to the file, and a discovery-engine:// link that opens the document in the app.
• Every call is recorded in the case's agent log.
• It never prompts when it isn't run from an interactive terminal. A command that needs a person fails with exit code 5 instead.

#Global options

#JSON output

With --json, every reply is one JSON document:

{"schema": "discovery.v1", "command": "doctor", "ok": true, "data": {}}

A failure has "ok": false and an error with code, message and hint. ok is true exactly when the exit code is 0.

Long-running commands (models fetch, watch, ingest run, ingest rescan) print JSON Lines: progress lines with an event key first, then the usual reply as the last line.

#Exit codes

#Citation formats

Commands accept the same citations the app shows: DOC-0417 p.2, EMAIL-0007 msg 3, SHEET-0033 Ledger!row 118, AUD-0004 00:16, VID-0003 00:05 screen, or a Bates number. See Citations, IDs and Bates numbers.

#Setup and health

#Cases

#Reading the case

--workers defaults to half the processor cores, but no more than fit in memory (about 2.5 GB each).

#Finding evidence

#Filters shared by many commands

search, timeline, doc list, doc cards, review start and review add accept:

#Commands

#Connections

Example of an event: --event "Wire transfer: wire, transfer @2019-01-01..2019-06-30".

#Reviews

A review is a record of a call (relevant, not relevant, unsure) on each document that could answer a question. It is kept in the case.

#Highlights

There is no command to approve or reject a highlight. That is done by a person, on the Highlights screen.

#Exports

From the command line, exports are sanitized by default; add --real-names for the attorney's copy. The output folder can't be inside the case's source folder.

#Your own notes in SQL

#For people, not agents

discovery install-cli puts the command on the computer, like the Start Up button. It's hidden from --help because an agent has no reason to run it.

If discovery isn't installed yet, you can reach the same commands through the app's bundled Python, for example on a Mac:

"/Applications/Discovery Engine.app/Contents/Resources/engine/python/bin/python3" -I -B -m discovery_engine doctor

and on Windows:

& "$env:LOCALAPPDATA\Discovery Engine\engine\python\python.exe" -I -B -m discovery_engine doctor