inillucent_cli/command/

registry.rs

//! Every command, as data.
//!
//! Invariant: **this array is the only list.** `inillucent --help`,
//! `inillucent <verb>`'s argument parsing, `inillucent-mcp`'s `tools/list` and
//! every JSON Schema it publishes are derived from it, and
//! `command_parity.rs` fails the build if any of them stops agreeing.
//!
//! The descriptions are written for two readers at once. A person runs
//! `inillucent help query`; a 27B model reads the same sentence as a tool
//! description and has one attempt at getting the call right. That is why they
//! say what a parameter *is for* rather than restating its name, and why the
//! ones with a trap in them - `limit` cutting the rows handed back but not the
//! count, `params` being positional - say so.

use super::verbs;
use super::{Command, Kind, Param, Writes, DB, FORMAT, LIMIT};

/// The parameters `query` takes.
const QUERY_PARAMS: &[Param] = &[
    Param {
        name: "sql",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "The SQL to run. One statement. Use ?1, ?2 ... for values you pass in \
                      'params' rather than pasting them into the text.",
    },
    Param {
        name: "params",
        kind: Kind::Values,
        required: false,
        positional: false,
        description: "The values for ?1, ?2 ... in order, as a JSON array of strings, numbers, \
                      booleans or nulls. An array of numbers is a vector and \
                      {\"blob\":\"<hex>\"} is bytes. Binding is how you avoid quoting mistakes \
                      and SQL injection.",
    },
    Param {
        name: "params-file",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "A file holding the JSON array for 'params', or - for standard input. What \
                      a wrapper that spawns this binary uses: a command line has a length \
                      ceiling, about 32 KB on Windows, and a parameter past it fails outright.",
    },
    LIMIT,
    DB,
    FORMAT,
];

/// The parameters `exec` takes.
const EXEC_PARAMS: &[Param] = &[
    Param {
        name: "sql",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "One statement to run for its effect: INSERT, UPDATE, DELETE, CREATE, DROP, \
                      ALTER or a PRAGMA that sets something.",
    },
    Param {
        name: "params",
        kind: Kind::Values,
        required: false,
        positional: false,
        description: "The values for ?1, ?2 ... in order, as a JSON array. An array of numbers \
                      is a vector and {\"blob\":\"<hex>\"} is bytes.",
    },
    Param {
        name: "params-file",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "A file holding the JSON array for 'params', or - for standard input. What \
                      a wrapper that spawns this binary uses: a command line has a length \
                      ceiling, about 32 KB on Windows, and a parameter past it fails outright.",
    },
    DB,
    FORMAT,
];

/// The parameters `batch` takes.
const BATCH_PARAMS: &[Param] = &[
    Param {
        name: "sql",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "Several statements separated by semicolons. They run as one transaction: \
                      either all of them take effect or none of them do.",
    },
    DB,
    FORMAT,
];

/// The parameters `run` takes.
const RUN_PARAMS: &[Param] = &[
    Param {
        name: "input",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "Shell input, exactly as you would type it: SQL statements ending in a \
                      semicolon, and dot commands such as '.schema' or '.mode box' on their own \
                      lines. Everything the interactive shell can do is reachable here.",
    },
    DB,
];

/// The parameters `create` takes.
const CREATE_PARAMS: &[Param] = &[
    Param {
        name: "path",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "Where to make the new database file. It refuses a path that already \
                      exists rather than overwriting it.",
    },
    FORMAT,
];

/// The parameters a pattern-filtered listing takes.
const PATTERN_PARAMS: &[Param] = &[
    Param {
        name: "pattern",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "A LIKE pattern to filter the names by, such as 'user%'. Omit it for all \
                      of them.",
    },
    DB,
    FORMAT,
];

/// The parameters `schema` takes.
const SCHEMA_PARAMS: &[Param] = &[
    Param {
        name: "pattern",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "A LIKE pattern naming which objects to show. Omit it for the whole schema.",
    },
    Param {
        name: "indent",
        kind: Kind::Boolean,
        required: false,
        positional: false,
        description: "Pretty-print each CREATE statement over several lines instead of one.",
    },
    DB,
    FORMAT,
];

/// The parameters `describe` takes.
const DESCRIBE_PARAMS: &[Param] = &[
    Param {
        name: "table",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "The table or view to describe, by its exact name. Use 'tables' first if \
                      you are not sure what it is called.",
    },
    DB,
    FORMAT,
];

/// The parameters the database-only commands take.
const DB_ONLY: &[Param] = &[DB, FORMAT];

/// The parameters `explain` takes.
const EXPLAIN_PARAMS: &[Param] = &[
    Param {
        name: "sql",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "The statement whose plan you want. It is not run - this only shows which \
                      indexes and scans the planner chose.",
    },
    DB,
    FORMAT,
];

/// The parameters `import` takes.
const IMPORT_PARAMS: &[Param] = &[
    Param {
        name: "file",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "The delimited file to read.",
    },
    Param {
        name: "table",
        kind: Kind::Text,
        required: true,
        positional: false,
        description: "The table to load into. If it does not exist it is created, taking its \
                      column names from the file's first row.",
    },
    Param {
        name: "format",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "'csv' (the default, RFC 4180 quoting), 'tabs', or 'ascii' for \\037 and \
                      \\036 separated input.",
    },
    Param {
        name: "skip",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "How many leading rows to ignore, for a file with a preamble above its \
                      header.",
    },
    DB,
];

/// The parameters `embed` takes.
const EMBED_PARAMS: &[Param] = &[
    Param {
        name: "table",
        kind: Kind::Text,
        required: true,
        positional: false,
        description:
            "The table to fill. An ordinary table with a VECTOR(768) or BLOB column, or an \
                      inillucent_search table, whose vector column can be updated by rowid.",
    },
    Param {
        name: "text",
        kind: Kind::Text,
        required: true,
        positional: false,
        description: "The column holding the text to embed. A row whose text is NULL or empty is \
                      skipped and counted.",
    },
    Param {
        name: "vector",
        kind: Kind::Text,
        required: true,
        positional: false,
        description:
            "The column to write the vectors into. Only rows where it IS NULL are embedded, \
                      so a stopped run continues where it ended.",
    },
    Param {
        name: "prefix",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "Text put in front of every value before it is embedded, exactly as \
                      embed('search_document: ' || body) does. For nomic-embed-text-v1.5 use \
                      'search_document: '. The default is no prefix.",
    },
    Param {
        name: "device",
        kind: Kind::Text,
        required: false,
        positional: false,
        description:
            "The processor: 'cpu', 'cuda' or 'cuda:N' for card N. Without it the machine's \
                      setting applies (INILLUCENT_EMBED_DEVICE, then what setup-embeddings \
                      recorded, then the processor). A cuda device that will not start is an error \
                      naming 'inillucent setup-embeddings runtime --gpu', and never runs on the \
                      processor.",
    },
    Param {
        name: "threads",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "Threads ONNX Runtime uses inside one operator, per session. Without it the \
                      machine's setting applies.",
    },
    Param {
        name: "sessions",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "How many model sessions to open on the device and run at once. The default \
                      is 1. Two sessions on one card were measured 2.1 times faster than one.",
    },
    Param {
        name: "batch-size",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "Most texts in one call to the model. The default is 16. A batch is also \
                      limited by a memory ceiling that shrinks it when the texts are long.",
    },
    Param {
        name: "commit-every",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "How many rows to embed and write in one transaction. The default is 1024. A \
                      crash loses at most one transaction.",
    },
    Param {
        name: "all",
        kind: Kind::Boolean,
        required: false,
        positional: false,
        description: "Embed every row again, including rows that already have a vector.",
    },
    DB,
    FORMAT,
];

/// The parameters `export` takes.
const EXPORT_PARAMS: &[Param] = &[
    Param {
        name: "table",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "The table to write out whole. Give this or 'sql', not both.",
    },
    Param {
        name: "sql",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "A query whose rows to write out, when you want less than a whole table.",
    },
    Param {
        name: "format",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "csv, json, tabs, markdown, insert, quote, line or html. Defaults to csv.",
    },
    Param {
        name: "out",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "A file to write to. Omitted, the rows come back in the result instead.",
    },
    DB,
];

/// The parameters `dump` takes.
const DUMP_PARAMS: &[Param] = &[
    Param {
        name: "objects",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "A LIKE pattern for the tables, indexes, triggers or views to dump. Omit \
                      it for the whole database.",
    },
    Param {
        name: "data_only",
        kind: Kind::Boolean,
        required: false,
        positional: false,
        description: "Write only the INSERT statements, leaving out the CREATE statements.",
    },
    DB,
];

/// The parameters `backup` takes.
const BACKUP_PARAMS: &[Param] = &[
    Param {
        name: "file",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "Where to write the copy.",
    },
    DB,
];

/// The parameters `encrypt` and `decrypt` take.
const COPY_PARAMS: &[Param] = &[
    Param {
        name: "file",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "Where to write the copy. A file already there is refused, not replaced.",
    },
    DB,
];

/// The parameters `rekey` takes.
const REKEY_PARAMS: &[Param] = &[
    Param {
        name: "new-key-file",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "A file holding the new key. Without it the new key is read from the                       INILLUCENT_NEW_KEY environment variable. A key is never taken as a word                       on the command line, where every user of the machine can read it.",
    },
    DB,
];

/// The parameters `restore` takes.
const RESTORE_PARAMS: &[Param] = &[
    Param {
        name: "file",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "The copy to read back. It replaces what is in the open database.",
    },
    DB,
];

/// The parameters `analyze` takes.
const ANALYZE_PARAMS: &[Param] = &[
    Param {
        name: "table",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "One table to gather statistics for. Omit it for every table.",
    },
    DB,
    FORMAT,
];

/// The parameters `migrate` takes.
const MIGRATE_PARAMS: &[Param] = &[
    Param {
        name: "source",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "The SQLite database file to read, or a postgres:// or mysql:// connection \
                      URL. The source is never written to. A connection URL holds a password, \
                      and an argument is visible in the process list for the whole run - so it \
                      may be left out and given in INILLUCENT_SOURCE_URL instead, or written as \
                      '-' to read one line from standard input.",
    },
    Param {
        name: "destination",
        kind: Kind::Text,
        required: true,
        positional: false,
        description: "The .rdb file to build. It refuses to overwrite an existing file.",
    },
    Param {
        name: "kind",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "'sqlite' (the default for a path), 'postgres' or 'mysql' (the default for \
                      a URL written with that scheme), or 'index' for a legacy retrieval index.",
    },
    Param {
        name: "batch",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "Rows per destination transaction while copying from a server. Default \
                      10000. It changes how long the migration takes and nothing about what it \
                      produces.",
    },
    Param {
        name: "insecure-plaintext",
        kind: Kind::Boolean,
        required: false,
        positional: false,
        description: "Permit an unencrypted connection to a server. A migration to a host that \
                      is not a loopback address uses verified TLS, and refuses rather than \
                      falling back; this permits plaintext, and only together with \
                      sslmode=disable in the URL. Both are needed because either one alone is \
                      something people type without meaning it. The choice is recorded in the \
                      migration report.",
    },
];

/// The parameters `search` takes.
const SEARCH_PARAMS: &[Param] = &[
    Param {
        name: "query",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "What to search for, in FTS5 query syntax: bare words are ANDed, \
                      \"a phrase\" is quoted, and OR and NOT are available.",
    },
    Param {
        name: "table",
        kind: Kind::Text,
        required: true,
        positional: false,
        description: "The full-text table to search - one created with USING fts5(...) or \
                      USING inillucent_search(...).",
    },
    Param {
        name: "k",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "How many results to return, best first. Defaults to 10.",
    },
    Param {
        name: "rerank",
        kind: Kind::Boolean,
        required: false,
        positional: false,
        description: "Reorder the rows the search found with the reranker, which reads the query \
                      and each row together. The query text is passed as the question, so write \
                      it as plain words. Needs an inillucent_search table and the reranker, \
                      installed with 'inillucent setup-embeddings reranker'. On the processor \
                      60 rows take about 10 seconds; on a graphics card about a tenth of one.",
    },
    DB,
    FORMAT,
];

/// The parameters `vector-search` takes.
const VECTOR_PARAMS: &[Param] = &[
    Param {
        name: "table",
        kind: Kind::Text,
        required: true,
        positional: true,
        description: "The table holding the vectors.",
    },
    Param {
        name: "column",
        kind: Kind::Text,
        required: true,
        positional: false,
        description: "The VECTOR(N) column to measure against.",
    },
    Param {
        name: "vector",
        kind: Kind::Values,
        required: true,
        positional: false,
        description: "The query vector, as a JSON array of numbers with exactly N elements.",
    },
    Param {
        name: "k",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "How many nearest rows to return. Defaults to 10.",
    },
    Param {
        name: "measure",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "'cos' for cosine distance (the default), 'l2' for Euclidean, or 'dot' \
                      for the inner product.",
    },
    DB,
    FORMAT,
];

/// The parameters `capabilities` takes.
const CAPABILITY_PARAMS: &[Param] = &[
    Param {
        name: "name",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "One capability to ask about, such as 'triggers'. Omit it for the whole \
                      table. A name that is not in the table answers no, not yes.",
    },
    FORMAT,
];

/// The parameters `help` takes.
const HELP_PARAMS: &[Param] = &[
    Param {
        name: "topic",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "A command to explain in full. Omit it for the list of every command.",
    },
    FORMAT,
];

/// The parameters `setup-embeddings` takes.
const SETUP_PARAMS: &[Param] = &[
    Param {
        name: "component",
        kind: Kind::Text,
        required: false,
        positional: true,
        description: "What to install: 'all' for both halves, 'runtime' for the ONNX Runtime \
                      shared library on its own, 'model' for the embedding weights on their own, or \
                      'reranker' for the cross encoder that rerank() and a search naming question \
                      use (about 600 MB, and not part of 'all'). Omit it to report what is \
                      installed and download nothing.",
    },
    Param {
        name: "status",
        kind: Kind::Boolean,
        required: false,
        positional: false,
        description: "Say what is installed, where, and which residency profile is in force, and \
                      download nothing.",
    },
    Param {
        name: "residency",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "When the model is in memory: 'resident' keeps it for the life of the process, \
                      'on-demand' loads it per call and drops it, 'idle' or 'idle:90s' loads it on \
                      use and drops it after a quiet period. Recorded for this machine; \
                      INILLUCENT_EMBED_RESIDENCY overrides it for one process.",
    },
    Param {
        name: "threads",
        kind: Kind::Integer,
        required: false,
        positional: false,
        description: "How many threads ONNX Runtime uses inside one operator, for embed(), \
                      rerank() and a reranked search. Recorded for this machine; \
                      INILLUCENT_EMBED_THREADS overrides it for one process. Without it ONNX \
                      Runtime picks its own count. Four was the fastest single process setting \
                      measured for the embedding model.",
    },
    Param {
        name: "device",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "The processor the sessions run on: 'cpu', 'cuda' or 'cuda:N' for card N. \
                      Recorded for this machine; INILLUCENT_EMBED_DEVICE overrides it for one \
                      process. A cuda device that will not start is an error and never runs on \
                      the processor. It needs the runtime installed with '--gpu'.",
    },
    Param {
        name: "gpu",
        kind: Kind::Boolean,
        required: false,
        positional: false,
        description: "Install the ONNX Runtime build carrying the CUDA execution provider, which \
                      exists for Windows and Linux on x86-64 only. It is a much larger download and \
                      it needs a CUDA install of its own to be usable.",
    },
    Param {
        name: "force",
        kind: Kind::Boolean,
        required: false,
        positional: false,
        description: "Fetch and install again even when the files are already there and their \
                      digests match.",
    },
    Param {
        name: "onnxruntime-version",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "The ONNX Runtime version to install. Defaults to the one this build pins a \
                      digest for; any other version is fetched and reported as unverified.",
    },
    Param {
        name: "dir",
        kind: Kind::Text,
        required: false,
        positional: false,
        description: "Install somewhere other than the per-user directory. INILLUCENT_HOME does the \
                      same thing for every command at once.",
    },
    FORMAT,
];

/// The parameters `version` takes.
const VERSION_PARAMS: &[Param] = &[FORMAT];

/// Every command inillucent has, in the order `help` lists them.
pub static COMMANDS: &[Command] = &[
    Command {
        name: "query",
        summary: "Run a SELECT and get its rows back.",
        detail: "Use this for anything that reads. The rows come back as a table, or as typed \
                 JSON with output=json. 'total' is exact even when 'limit' cut the rows handed \
                 back, because the engine materialises the whole result - so a limit of 10 on a \
                 million-row query still costs what the million rows cost. Put a LIMIT in the SQL \
                 itself when you cannot afford that, where the planner can act on it.",
        params: QUERY_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::query,
    },
    Command {
        name: "exec",
        summary: "Run one statement that changes something, and get the row count back.",
        detail: "INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, or a PRAGMA that sets a value. A \
                 statement with RETURNING gives its rows back as well as its count.",
        params: EXEC_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: verbs::exec,
    },
    Command {
        name: "batch",
        summary: "Run several statements as one transaction.",
        detail: "Separate them with semicolons. Either all of them take effect or none of them \
                 do, which is what you want when creating a schema or loading related rows.",
        params: BATCH_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: verbs::batch,
    },
    Command {
        name: "run",
        summary: "Run shell input, dot commands and all, and get back what it printed.",
        detail: "The escape hatch, and the reason every dot command is reachable from every front \
                 end: this drives the same shell 'inillucent shell' does. Use it for the things \
                 that have no verb of their own - '.eqp on', '.parameter set', '.testcase', \
                 '.archive'. Run 'inillucent run \".help\"' for the full list of dot commands.",
        params: RUN_PARAMS,
        cli_only: None,
        // **The verb gate stands aside and the shell refuses the writes.**
        // `writes: true` here refused `--readonly run "SELECT count(*) FROM t;"`
        // and the `inillucent_run` MCP tool with it, although `run` is how a
        // read only agent reaches every dot command (task-2066 section 4.2,
        // item 26).
        writes: Writes::PerStatement,
        run: verbs::run_input,
    },
    Command {
        name: "create",
        summary: "Make a new, empty database file.",
        detail: "Refuses a path that already exists, so it can never destroy a database by being \
                 run twice. Every other command opens whatever it is pointed at.",
        params: CREATE_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: verbs::create,
    },
    Command {
        name: "tables",
        summary: "List the tables and views.",
        detail: "The names, with what each one is. System tables whose names begin with sqlite_ \
                 are left out.",
        params: PATTERN_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::tables,
    },
    Command {
        name: "describe",
        summary: "Everything about one table: columns, types, keys, indexes, row count and DDL.",
        detail: "Call this before writing SQL against a table you did not create. It answers in \
                 one call what four separate pragmas would, which matters because a caller that \
                 has to make four usually makes three and writes its query from an incomplete \
                 picture.",
        params: DESCRIBE_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::describe,
    },
    Command {
        name: "schema",
        summary: "Show the CREATE statements for the whole database or for what a pattern names.",
        detail: "The schema as SQL, which is the form you can paste into another database.",
        params: SCHEMA_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::schema,
    },
    Command {
        name: "indexes",
        summary: "List the indexes and the table each one is on.",
        detail: "Including the ones a UNIQUE constraint or a primary key created, which is why \
                 an index you did not write may appear here.",
        params: PATTERN_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::indexes,
    },
    Command {
        name: "databases",
        summary: "List the attached databases and the file behind each.",
        detail: "'main' is the one that was opened; others come from ATTACH. 'temp' is the \
                 session's own scratch database and has no file.",
        params: DB_ONLY,
        cli_only: None,
        writes: Writes::No,
        run: verbs::databases,
    },
    Command {
        name: "explain",
        summary: "Show the query plan for a statement without running it.",
        detail: "Which indexes are used, which scans are full, and in what order the tables are \
                 joined. This is how you find out why a query is slow before making it faster.",
        params: EXPLAIN_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::explain,
    },
    Command {
        name: "import",
        summary: "Load a CSV or tab-separated file into a table.",
        detail: "The table is created from the file's first row if it does not exist. Quoting is \
                 RFC 4180 unless a different format is asked for.",
        params: IMPORT_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: verbs::import,
    },
    Command {
        name: "embed",
        summary: "Fill a vector column with embeddings, on the processor or a graphics card.",
        detail: "Reads every row of --table whose --vector column IS NULL, embeds the --text column \
                 with the nomic-embed-text-v1.5 model, and writes the vectors in the layout embed() \
                 returns. It sorts the texts by length, groups them under a memory ceiling, and \
                 commits every --commit-every rows, so a stopped run continues where it ended. A \
                 corpus of 558,429 chunks took 22 minutes on a graphics card, where embed() in SQL, \
                 one row at a time on the processor, would take about 12 hours. It prints how many \
                 rows were embedded, how many were skipped because the text was NULL or empty, and \
                 how many were cut at the model's token limit, with the rowid of up to 20 of them. \
                 Needs the model: run 'inillucent setup-embeddings all' first, and \
                 'inillucent setup-embeddings runtime --gpu' for a card.",
        params: EMBED_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: crate::bulk_embed::embed_table,
    },
    Command {
        name: "export",
        summary: "Write a table or a query's rows out as CSV, JSON or one of six other formats.",
        detail: "With 'out' the rows go to a file and the result says so; without it they come \
                 back in the result, which is usually what an agent wants.",
        params: EXPORT_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::export,
    },
    Command {
        name: "dump",
        summary: "Render the database as the SQL that would rebuild it.",
        detail: "Schema and data, in dependency order, inside a transaction. This is the \
                 portable form: it is text, and another SQLite-speaking database will read it.",
        params: DUMP_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::dump,
    },
    Command {
        name: "backup",
        summary: "Write a copy of the database to another file.",
        detail: "A consistent copy taken while the database is open. The copy is a database, not \
                 a text dump.",
        params: BACKUP_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::backup,
    },
    Command {
        name: "encrypt",
        summary: "Write an encrypted copy of a plaintext database.",
        detail: "The copy is encrypted with the key from --key-file or INILLUCENT_KEY, and                  holds every row, index, view and trigger of the database --db names, which is                  read without the key. The source is left as it was: replace it with the copy                  once you have checked the copy opens.",
        params: COPY_PARAMS,
        cli_only: Some(
            "it takes its key from the program's own --key-file or environment, and an MCP              client has neither. Encrypt a database before serving it.",
        ),
        writes: Writes::No,
        run: verbs::encrypt,
    },
    Command {
        name: "decrypt",
        summary: "Write a plaintext copy of an encrypted database.",
        detail: "Opens the database --db names with the key from --key-file or INILLUCENT_KEY                  and writes every row, index, view and trigger to a file that is not                  encrypted. The encrypted database is left as it was.",
        params: COPY_PARAMS,
        cli_only: Some(
            "it writes every row of an encrypted database to disk unprotected, which is a              decision for the person who holds the key and not for an agent the database              is served to.",
        ),
        writes: Writes::No,
        run: verbs::decrypt,
    },
    Command {
        name: "rekey",
        summary: "Change the key an encrypted database is encrypted with.",
        detail: "Opens the database with the key from --key-file or INILLUCENT_KEY and moves it                  to the new key from --new-key-file or INILLUCENT_NEW_KEY. Only the header of                  each file is rewritten, so it takes the same time whatever the database's                  size, and the old key stops opening the database when it returns. PRAGMA                  rekey does the same from SQL.",
        params: REKEY_PARAMS,
        cli_only: Some(
            "an agent that could change the key could lock the database's owner out of it.",
        ),
        writes: Writes::Yes,
        run: verbs::rekey,
    },
    Command {
        name: "restore",
        summary: "Point this session at a backup file, in place of the database it opened.",
        detail: "The opposite of 'backup', and it does not overwrite anything: this engine's \
                 databases are whole files, so restoring is opening the other file rather than \
                 writing its pages over the one you are in. That means it lasts as long as the \
                 session does - useful from the shell and from 'run', where the statements after \
                 it read the restored file, and of no effect on its own, because a one-shot \
                 process ends immediately after. To replace a file, copy the backup over it. A \
                 backup file that is not there is refused rather than created empty.",
        params: RESTORE_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: verbs::restore,
    },
    Command {
        name: "checkpoint",
        summary: "Fold the write-ahead log back into the database file.",
        detail: "Writes go to a log first and are folded in later. Doing it now shrinks the log \
                 and is what you want before copying the file by hand.",
        params: DB_ONLY,
        cli_only: None,
        writes: Writes::Yes,
        run: verbs::checkpoint,
    },
    Command {
        name: "integrity-check",
        summary: "Read every page and report whether the database holds together.",
        detail: "Answers 'ok' on a healthy database. Anything else names what is wrong. It reads \
                 the whole file, so it costs what the file costs.",
        params: DB_ONLY,
        cli_only: None,
        writes: Writes::No,
        run: verbs::integrity_check,
    },
    Command {
        name: "analyze",
        summary: "Gather the statistics the query planner reads.",
        detail: "Run it after loading a lot of data. Without statistics the planner guesses at \
                 how selective an index is, and a wrong guess is the usual reason a query that \
                 should use an index does not.",
        params: ANALYZE_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: verbs::analyze,
    },
    Command {
        name: "stats",
        summary: "Report the page cache, the pool size and the shape of the file.",
        detail: "Cache hits and misses, how many pages the file holds and how many are free. \
                 This is where you look when a workload is slower than it should be.",
        params: DB_ONLY,
        cli_only: None,
        writes: Writes::No,
        run: verbs::stats,
    },
    Command {
        name: "search",
        summary: "Full-text search over an FTS5 or inillucent_search table.",
        detail: "Writes the MATCH ... ORDER BY rank idiom for you, which is the part nobody \
                 remembers. The table has to be a full-text one; 'describe' will show you \
                 whether it is.",
        params: SEARCH_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::search,
    },
    Command {
        name: "vector-search",
        summary: "Find the rows whose vector is nearest to one you supply.",
        detail: "Over a VECTOR(N) column, by cosine distance unless you ask for another measure. \
                 If there is an HNSW index on the column the planner uses it; if there is not, \
                 this is an exhaustive scan and is still correct.",
        params: VECTOR_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::vector_search,
    },
    Command {
        name: "capabilities",
        summary: "Ask what this engine can do before composing a statement.",
        detail: "Every row is checked against the running engine by a test, in both directions - \
                 a claim of support that fails and a claim of absence that now works each turn \
                 the build red. So this is worth trusting in a way a hand-maintained feature \
                 list is not. A name that is not in the table answers no, because a capability \
                 that was never declared was never checked.",
        params: CAPABILITY_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::capabilities,
    },
    Command {
        name: "functions",
        summary: "List the SQL functions this engine answers.",
        detail: "From the engine's own register, which is compared against the reference \
                 library's on every build - so this is what actually exists rather than what was \
                 documented once.",
        params: PATTERN_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::functions,
    },
    Command {
        name: "migrate",
        summary: "Build an inillucent database from a SQLite file, PostgreSQL or MySQL.",
        detail: "Reads the source and writes a new .rdb with the same rows. A path is a SQLite \
                 database file; a postgres:// or mysql:// URL is a running server, read inside \
                 one repeatable-read snapshot so that every table is as of one instant. The \
                 source is never written to and the destination is never overwritten: the new \
                 file is staged under another name and published by a rename, so a half-written \
                 database never sits where an application would open it. A server migration is \
                 verified per table by row count and by an order-independent digest, and nothing \
                 that fails a check is published.",
        params: MIGRATE_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: verbs::migrate,
    },
    Command {
        name: "setup-embeddings",
        summary: "Download and install the embedding model and the runtime it needs.",
        detail: "One command, on Windows, macOS and Linux. It fetches ONNX Runtime and the \
                 nomic-embed-text-v1.5 weights into a per-user directory, checks every byte \
                 against a digest pinned in this build, and leaves the engine able to answer \
                 embed(TEXT) with nothing exported by hand - so a mismatch is a refusal that \
                 names both digests rather than a shared library that loads and misbehaves. \
                 Name what you want: 'all' installs both halves, 'runtime' and 'model' one \
                 each. Run with no component at all and it reports what is installed and \
                 downloads nothing, which is what stops a 620 MB fetch being a surprise; \
                 '--status' does the same explicitly. About 620 MB the first time and \
                 nothing on a later run. '--residency' chooses when the model is in memory: \
                 'resident' keeps it, which is about 1.9 GB held and 12 to 36 ms a query; \
                 'on-demand' loads it per call, which holds nothing and costs about 0.8 s a \
                 query; 'idle' or 'idle:90s' loads it on use and drops it after a quiet \
                 period, which is the default and pays the load once for a burst of \
                 questions.",
        params: SETUP_PARAMS,
        cli_only: None,
        writes: Writes::Yes,
        run: crate::setup::setup_embeddings,
    },
    Command {
        name: "version",
        summary: "Report the engine, the dialect and the driver versions.",
        detail: "The SQLite version named here is the dialect this engine implements, not a \
                 library it links. There is no SQLite in this binary.",
        params: VERSION_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::version,
    },
    Command {
        name: "help",
        summary: "List every command, or explain one in full.",
        detail: "With no topic it prints the table. With one it prints that command's usage, \
                 what it is for, and every parameter it takes.",
        params: HELP_PARAMS,
        cli_only: None,
        writes: Writes::No,
        run: verbs::help,
    },
    Command {
        name: "shell",
        summary: "Start the interactive shell.",
        detail: "The sqlite3-shaped REPL, with all 63 dot commands. Everything it can do is also \
                 reachable non-interactively through 'run'.",
        params: &[],
        cli_only: Some(
            "it is a terminal REPL: it reads a keyboard and writes a screen, and neither exists \
             at the other end of an MCP call. Use 'run' instead, which drives the same shell.",
        ),
        writes: Writes::Yes,
        run: verbs::shell_placeholder,
    },
    Command {
        name: "mcp",
        summary: "Serve these commands to an agent over MCP on standard input and output.",
        detail: "Every command in this table that is not marked cli-only becomes a tool named \
                 inillucent_<command>, with this same description and these same parameters.",
        params: &[],
        cli_only: Some(
            "it is the server that would be exposing the tools, so offering it as one of them \
             would let a client ask the server to serve itself.",
        ),
        writes: Writes::Yes,
        run: verbs::mcp_placeholder,
    },
];