Enum Commands 

pub enum Commands {
    Init(InitArgs),
    Remember(RememberArgs),
    RememberBatch(RememberBatchArgs),
    Ingest(Box<IngestArgs>),
    Recall(RecallArgs),
    Read(ReadArgs),
    List(ListArgs),
    Forget(ForgetArgs),
    Purge(PurgeArgs),
    Rename(RenameArgs),
    SplitBody(SplitBodyArgs),
    Edit(EditArgs),
    History(HistoryArgs),
    Restore(RestoreArgs),
    HybridSearch(HybridSearchArgs),
    Health(HealthArgs),
    Migrate(MigrateArgs),
    NamespaceDetect(NamespaceDetectArgs),
    Optimize(OptimizeArgs),
    Stats(StatsArgs),
    SyncSafeCopy(SyncSafeCopyArgs),
    Backup(BackupArgs),
    Vacuum(VacuumArgs),
    Link(LinkArgs),
    Unlink(UnlinkArgs),
    DeepResearch(DeepResearchArgs),
    Related(RelatedArgs),
    Graph(GraphArgs),
    Export(ExportArgs),
    Fts(FtsArgs),
    Vec(VecArgs),
    PruneRelations(PruneRelationsArgs),
    PruneNer(PruneNerArgs),
    Slots(SlotsArgs),
    Embedding(EmbeddingArgs),
    PendingEmbeddings(PendingEmbeddingsArgs),
    CleanupOrphans(CleanupOrphansArgs),
    MemoryEntities(MemoryEntitiesArgs),
    Cache(CacheArgs),
    DeleteEntity(DeleteEntityArgs),
    Reclassify(ReclassifyArgs),
    RenameEntity(RenameEntityArgs),
    MergeEntities(MergeEntitiesArgs),
    Enrich(Box<EnrichArgs>),
    ReclassifyRelation(ReclassifyRelationArgs),
    NormalizeEntities(NormalizeEntitiesArgs),
    Completions(CompletionsArgs),
    Schema(SchemaArgs),
    DebugSchema(DebugSchemaArgs),
    Config(ConfigArgs),
}

Every subcommand the CLI dispatches, in the order --help renders them.

Variants

Init(InitArgs)

Initialize the database and write the schema (no model download, no subprocess)

Remember(RememberArgs)

Save a memory with optional entity graph

RememberBatch(RememberBatchArgs)

Batch-create memories from NDJSON stdin (one invocation, one slot)

Ingest(Box<IngestArgs>)

Bulk-ingest every file under a directory as separate memories (NDJSON output)

Recall(RecallArgs)

Search memories semantically

Read(ReadArgs)

Read a memory by exact name

List(ListArgs)

List memories with filters

Forget(ForgetArgs)

Soft-delete a memory

Purge(PurgeArgs)

Permanently delete soft-deleted memories

Rename(RenameArgs)

Rename a memory preserving history

SplitBody(SplitBodyArgs)

Split an oversized memory body into N child memories (v1.1.03, GAP-V8)

Edit(EditArgs)

Edit a memory’s body or description

History(HistoryArgs)

List all versions of a memory

Restore(RestoreArgs)

Restore a memory to a previous version

HybridSearch(HybridSearchArgs)

Search using hybrid vector + full-text search

Health(HealthArgs)

Show database health

Migrate(MigrateArgs)

Apply pending schema migrations

NamespaceDetect(NamespaceDetectArgs)

Resolve namespace precedence for the current invocation

Optimize(OptimizeArgs)

Run PRAGMA optimize on the database

Stats(StatsArgs)

Show database statistics

SyncSafeCopy(SyncSafeCopyArgs)

Create a checkpointed copy safe for file sync

Backup(BackupArgs)

Back up the database using the SQLite Online Backup API

Vacuum(VacuumArgs)

Run VACUUM after checkpointing the WAL

Link(LinkArgs)

Create an explicit relationship between two entities

Unlink(UnlinkArgs)

Remove a specific relationship between two entities

DeepResearch(DeepResearchArgs)

Deep parallel multi-hop GraphRAG research

Related(RelatedArgs)

List memories connected via the entity graph

Graph(GraphArgs)

Export a graph snapshot in json, dot or mermaid

Export(ExportArgs)

Export memories as NDJSON (one JSON line per memory, plus a summary line)

Fts(FtsArgs)

FTS5 full-text search index management (rebuild or check)

Vec(VecArgs)

Vector index maintenance (orphan detection, purge, stats) — G39

PruneRelations(PruneRelationsArgs)

Bulk-delete all relationships of a given type (e.g. mentions)

PruneNer(PruneNerArgs)

Remove NER bindings (memory_entities rows) for an entity or all entities

Slots(SlotsArgs)

Inspect and manage cross-process LLM slot semaphore (GAP-004, v1.0.82)

Embedding(EmbeddingArgs)

Health and per-entry inspection of the pending-embeddings queue (GAP-005, v1.0.82)

PendingEmbeddings(PendingEmbeddingsArgs)

Batch operations over the pending-embeddings queue (GAP-005, v1.0.82)

CleanupOrphans(CleanupOrphansArgs)

Remove entities that have no memories and no relationships

MemoryEntities(MemoryEntitiesArgs)

List entities linked to a specific memory

Cache(CacheArgs)

Manage cached resources (embedding models, etc.)

DeleteEntity(DeleteEntityArgs)

Delete an entity and all its relationships from the graph

Reclassify(ReclassifyArgs)

Reclassify one entity or a batch of entities to a new type

RenameEntity(RenameEntityArgs)

Rename an entity preserving all relationships and memory bindings

MergeEntities(MergeEntitiesArgs)

Merge multiple source entities into a single target entity

Enrich(Box<EnrichArgs>)

Enrich graph memories and entities using an LLM provider

ReclassifyRelation(ReclassifyRelationArgs)

Reclassify relationship types across the graph using rules or LLM judgment

NormalizeEntities(NormalizeEntitiesArgs)

Normalize entity names (deduplicate, kebab-case, merge near-duplicates)

Completions(CompletionsArgs)

Generate shell completions for Bash, Zsh, Fish, PowerShell, or Elvish

Schema(SchemaArgs)

List every shipped JSON Schema, or emit one by id (--name <ID>)

DebugSchema(DebugSchemaArgs)

debug-schema subcommand.

Config(ConfigArgs)

Manage API keys and diagnose provider configuration (v1.0.93)

Implementations

impl Commands

pub fn agent_surface_slug(&self) -> Option<&'static str>

Names the subcommand for crate::agent_surface alias suppression.

The suppression table used to match on the KEY alone, so results meant the same thing everywhere. It does not: in recall, results really is the concatenation of direct_matches and graph_matches, so dropping the halves loses nothing. In hybrid-search the two arrays are DISJOINT by construction — the graph expansion skips every id already fused — and they do not even hold the same type. Suppressing there deleted unique rows and then labelled them redundant, which is worse than losing them silently: the envelope asserted the removal was safe.

None for every subcommand that declares no alias, which makes the default fail-safe: a new command is never suppressed until someone adds it to the table deliberately. GAP-SG-274: graph reports TWO slugs, because it emits two shapes.

The NDJSON snapshot emits one self-contained record per line, discriminated by a kind field valued node, edge or summary; every other form of graph emits a single envelope in which kind is instead the deprecated alias of an entity’s type. One slug for both made the vocabulary layer blind to a distinction Self::streams was already computing three methods away, which is why a field name meaning two different things had to be excluded everywhere rather than scoped where it is unambiguous.

pub fn mutates(&self) -> bool

true when this subcommand can change durable state.

GAP-SG-205 reads it to decide whether the target database may be inherited from ambient configuration; crate::agent_surface::gate reads it to decide whether a refusal is still safe.

The refusal question is the sharper one. The agent-native surface runs at OUTPUT time, after the handler has already done its work, so refusing there would hand the caller a non-zero exit for an operation that succeeded — and a caller that retries a succeeded remember writes the memory twice. The gate therefore stays silent on anything this reports as mutating.

Read-only variants are listed EXPLICITLY and everything else answers true. The default has to be the conservative one: a subcommand added later and forgotten here loses a refusal it might have wanted, which costs a diagnostic, while the opposite default would let the gate fire after an unlisted write, which costs data.

pub fn persists(&self) -> bool

true when this subcommand actually persists, so its envelope is a receipt.

GAP-SG-206. Neither half answers this on its own. Self::mutates lists the read-only variants explicitly and answers true for all the rest, so it reports true for config list-keys, embedding list and fts check, which write nothing — right default for a refusal fence, wrong one for withholding an answer. Self::may_inherit_target classifies exactly those split families at the subcommand level.

The conjunction is not a new list: Cli::install_write_policy already asks precisely this question to decide whether the target must be named in the argv, which is the same question — “did something get written”. Naming it once is what stops a third hand-written copy from drifting away from the other two.

That hook is a plain code span rather than an intra-doc link because it is private, and rustdoc::private_intra_doc_links — denied in Cargo.toml — rejects a link from public documentation to an item the public documentation does not contain. tests/rustdoc_link_gate.rs now catches that class, which cargo test and cargo clippy are both blind to.

pub fn streams(&self) -> bool

true when this subcommand emits one self-contained record per line.

GAP-SG-209. crate::agent_surface::gate reads it to refuse the knobs that need a complete set, because the surface runs once per emitted envelope and a stream has no complete set by construction. Measured: --count-only export --limit 10 answered with eleven {"count":1} lines.

The property belongs to the SUBCOMMAND and not to the emitting function, which is the distinction that makes this a list rather than a flag on emit_json_compact. That function is also how config path, slots release and embedding list emit ONE envelope; keying the refusal off it would have rejected --count-only config path, which is perfectly answerable.

Streaming variants are listed EXPLICITLY and everything else answers false. The conservative default is the opposite of Self::mutates here, and deliberately so: a subcommand added later and forgotten keeps exactly today’s behaviour, while the opposite default would refuse flags on a command that can honour them perfectly well.

GAP-SG-229 added graph --format ndjson, which had been streaming since v1.0.35 without ever answering true here. The consequence was worse than a missing refusal: render_ndjson_streaming returns before the surface layer runs, so --select, --filter, --sort and --dedupe-by were ACCEPTED and then IGNORED, with no refusal and no warning — the exact shape of “flag aceita e silenciosamente ignorada” this project catalogues.

The format has to be read from args, and it can be: this predicate matches on the parsed arguments exactly as Self::mutates already does for graph recompute-degree. GAP-SG-274 gave Self::agent_surface_slug the same reach through the shared is_graph_ndjson helper, so the two no longer disagree about which shape of graph is in front of them. That helper is a plain code span rather than an intra-doc link because it is private, and rustdoc::private_intra_doc_links — denied in Cargo.toml — rejects a link from public documentation to an item the public documentation does not contain, exactly as Self::persists records for its own hook. The --json override is mirrored from graph_export::handlers, where it promotes the format to Json and turns the streaming path off entirely; forgetting it here would refuse whole-set knobs on an invocation that emits a single envelope.

dot and mermaid stay outside: they are rendered text, not JSON, so there is no record for a knob to act on.

pub fn may_inherit_target(&self) -> bool

Whether this subcommand may resolve its target from ambient configuration.

GAP-SG-207. Self::mutates answers “does this change durable state”; this answers “is naming the target nonetheless optional for THIS invocation”. The two differ, and reusing mutates alone would have been a defect: it lists the read-only variants explicitly and answers true for everything else, which is the right conservative default for the output-time refusal fence and the WRONG one here. For the fence a mistaken true costs a diagnostic; here it would cost a false refusal on a command that has no side effect to protect — fts check, vec stats, embedding list and embedding status all read and write nothing.

So the families whose subcommands split between reading and writing are classified at the SUBCOMMAND level. The Explicit Target Designation rule governs side effects, and a read inherits no authority it could misuse.

Enforcement lives in crate::paths::AppPaths::resolve. That placement keeps this list short: a subcommand that never resolves a database — config, completions, locale, slots, cache — is exempt by construction and needs no entry here at all.

pub fn is_embedding_heavy(&self) -> bool

Returns true for subcommands that load the ONNX model locally.

pub fn uses_cli_slot(&self) -> bool

Return whether this command occupies a CLI concurrency slot.

pub fn tolerates_missing_embedding_key(&self) -> bool

Read-only / no-embedding subcommands that MUST run without an embedding API key. init warms a best-effort smoke test internally and degrades to ok_no_embedding when the backend is unreachable; the enrich queue inspectors (--status / --list-dead / --requeue-dead / --prune-dead-orphans) never embed and never call the LLM. The eager OpenRouter key preflight in main must skip its hard-fail for these.

Trait Implementations

impl Debug for Commands

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for Commands

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for Commands

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand