Struct Cli 

pub struct Cli {

    pub max_concurrency: Option<usize>,
    pub wait_lock: Option<u64>,
    pub skip_memory_guard: bool,
    pub fail_on_degraded: bool,
    pub lang: Option<Language>,
    pub tz: Option<Tz>,
    pub config_dir: Option<PathBuf>,
    pub cache_dir: Option<PathBuf>,
    pub verbose: u8,
    pub quiet: bool,
    pub embedding_dim: Option<u64>,
    pub llm_backend: Option<LlmBackendChoice>,
    pub llm_model: Option<String>,
    pub llm_fallback: Option<String>,
    pub skip_embedding_on_failure: bool,
    pub llm_max_host_concurrency: Option<u32>,
    pub llm_slot_wait_secs: Option<u64>,
    pub llm_slot_no_wait: bool,
    pub embedding_backend: Option<EmbeddingBackendChoice>,
    pub embedding_model: Option<String>,
    pub openrouter_api_key: Option<String>,
    pub openrouter_timeout: Option<u64>,
    pub select: Vec<String>,
    pub filter: Vec<String>,
    pub filter_scope: Option<FilterScope>,
    pub allow_unknown_keys: bool,
    pub use_active: bool,
    pub max_items: Option<usize>,
    pub sort: Option<String>,
    pub dedupe_by: Option<String>,
    pub count_only: bool,
    pub truncate_content: Option<usize>,
    pub max_output_bytes: Option<usize>,
    pub no_input: bool,
    pub command: Option<Commands>,
}

CLI.

Fields

max_concurrency: Option<usize>

Maximum number of simultaneous CLI invocations allowed (default: 4).

Caps the counting semaphore used for CLI concurrency slots. The value must stay within [1, 2×nCPUs]. Values above the ceiling are rejected with exit 2.

wait_lock: Option<u64>

Wait up to SECONDS for a free concurrency slot before giving up (exit 75).

Useful in retrying agent pipelines: the process polls every 500 ms until a slot opens or the timeout expires. Default: 300s (5 minutes).

skip_memory_guard: bool

Skip the available-memory check before loading the model.

Exclusive use in automated tests where real allocation does not occur.

fail_on_degraded: bool

Fail instead of degrading when the query embedding cannot be produced.

recall and hybrid-search fall back to FTS5-only ranking when the provider is unreachable, raise vec_degraded on the envelope, and exit 0. That is the right default for a human reading results, and the wrong one for an agent that parses .results and never looks at the flags: it silently receives a keyword search where it asked for a hybrid one.

Under this flag a degraded read exits non-zero with the usual error envelope, so the retry verdict travels with it. A degradation the caller ASKED for with --fallback-fts-only is deliberate and never fails.

lang: Option<Language>

Language for human-facing stderr messages. Accepts en or pt.

Without the flag, detection uses XDG i18n.lang then OS locale (LC_ALL/LC_MESSAGES/LANG). JSON stdout stays deterministic and identical across languages; only human-facing strings are affected.

tz: Option<Tz>

Time zone for *_iso fields in JSON output (for example America/Sao_Paulo).

Accepts any IANA time zone name. Without the flag, it falls back to XDG display.tz; if unset, UTC is used. Integer epoch fields are not affected.

config_dir: Option<PathBuf>

Directory holding config.toml. Overrides the OS config directory.

Precedence (G-T-XDG-04): this flag > OS default. It deliberately does NOT consult a config set key, because the config file itself lives in this directory and reading it to find itself would be circular. Hidden: it exists for hermetic test isolation and sandboxed hosts.

cache_dir: Option<PathBuf>

Directory for lock files, model files and other cache artifacts.

Precedence (G-T-XDG-04): this flag > XDG cache.dir > OS default. Hidden for the same reason as --config-dir.

verbose: u8

Increase logging verbosity (-v=info, -vv=debug, -vvv=trace).

Overrides XDG log.level when present. Logs are emitted to stderr; JSON stdout is unaffected.

quiet: bool

Suppress non-error tracing on stderr (sets log level to error).

Prefer this in pipelines that capture stdout JSON (> out.json). Never combine stdout and stderr into the same file (&> / 2>&1) — that contaminates the JSON envelope (v1.1.05 Bug 2). Conflicts with -v / --verbose only in spirit: quiet wins when both are present.

embedding_dim: Option<u64>

Embedding dimensionality override (default 1024 since v1.2.0).

Precedence: this flag > XDG embedding.dim > the dim recorded in the database schema_meta > 1024. Existing databases keep their recorded dimensionality automatically; use this flag only to migrate a corpus to a new dimensionality (followed by enrich --operation re-embed). Range: [8, 4096].

llm_backend: Option<LlmBackendChoice>

LLM backend for embedding. Accepts openrouter (OpenRouter REST) or none (skips embedding; useful for tests). Prefer the flag; optional XDG llm.backend via config set.

Kept Option with no default_value_t, for the reason --llm-fallback already documents below: a clap default makes the field always Some, which silently swallows the XDG layer the doc promises. The default lives in crate::runtime_config::llm_backend instead, so flag > XDG > open-router actually resolves.

llm_model: Option<String>

v1.0.82 (GAP-003): model to invoke on the chosen backend. Prefer the flag; optional XDG llm.model.

llm_fallback: Option<String>

Chain of LLM backends tried in order when the primary fails.

Defaults to none. The default lives in the runtime registry rather than in default_value here on purpose: a clap default makes the field always Some, which silently swallows the XDG layer the doc promises — config set llm.fallback would have been read by nothing. Leaving it None when unset is what lets flag > XDG > constant actually resolve.

skip_embedding_on_failure: bool

v1.0.82 (GAP-005): persists with a NULL embedding when all backends in the chain fail. The memory stays in pending_embeddings for reprocessing via embedding retry. Prefer the flag; optional XDG XDG llm.skip_embedding_on_failure.

llm_max_host_concurrency: Option<u32>

Host-wide ceiling of concurrent LLM slots. Default derived from ncpus.

Prefer the flag; optional XDG llm.max_host_concurrency.

llm_slot_wait_secs: Option<u64>

v1.0.82 (GAP-004): seconds to wait for a free LLM slot before failing with exit 75. Default 30s. Prefer the flag; optional XDG XDG llm.slot_wait_secs.

llm_slot_no_wait: bool

v1.0.82 (GAP-004): if set, fails immediately (exit 75) when no LLM slot is free. Prefer the flag; optional XDG XDG llm.slot_no_wait.

embedding_backend: Option<EmbeddingBackendChoice>

Embedding backend selector.

openrouter uses the REST API and requires a stored key. auto resolves to the same path when a key is reachable and degrades to no embedding when it is not. There is no subprocess backend: generation happens over HTTP, in-process, one shot.

Prefer the flag; optional XDG config set embedding.backend.

Kept Option with no default_value_t: a clap default makes the field always Some and the XDG layer promised right above would be read by nothing. The default lives in crate::runtime_config::embedding_backend instead.

embedding_model: Option<String>

v1.0.93: embedding model for the OpenRouter API. Required when --embedding-backend openrouter. Prefer the flag; optional XDG embedding.model.

openrouter_api_key: Option<String>

OpenRouter API key for a single invocation.

Prefer config add-key --provider openrouter --from-stdin, which stores the key at rest under XDG with mode 0600 and keeps it out of both the shell history and the process table. No environment variable supplies this value: the product never reads one (G-T-XDG-04).

openrouter_timeout: Option<u64>

Per-request budget, in seconds, for every OpenRouter call.

Global because the deadline binds the EMBEDDING client too, and that client is built once per process at startup. Declared only on enrich, the flag reached the chat path and nothing else: remember, ingest, edit, restore and split-body were pinned to the compiled default with no way to widen it, and a slow provider turned into exit 11 with no operator recourse. enrich --openrouter-timeout <N> keeps working unchanged, because a clap global argument accepts being written at the subcommand position.

Kept optional so an EXPLICIT value is distinguishable from an omitted one, which is what lets flag > XDG > constant resolve instead of the flag always winning with a default nobody asked for.

select: Vec<String>

GAP-SG-142: keep only these keys in each result object (comma separated).

Accepts dotted paths (stats.total). Keys missing from an element are skipped rather than emitted as null, so a projection never invents fields. Envelopes without a result array are projected themselves. --fields is an accepted spelling of the same flag.

filter: Vec<String>

GAP-SG-142: keep only result elements satisfying EXPR.

Grammar: key=value, key!=value, key~substring (case-insensitive containment). == is a synonym of =. Repeat the flag to conjoin predicates with AND. A malformed expression fails fast with exit 2 so a typo is never mistaken for an empty result set. Failure envelopes are never filtered: error: true / ok: false always reaches the caller.

filter_scope: Option<FilterScope>

GAP-SG-201: declare what --filter is allowed to observe.

Omitted, a predicate over a page the query already truncated is refused with exit 2, because the answer would describe a set the predicate never saw: --filter type=skill list reports 39 of 1892 memories, and the same request with --limit 50 reported 0. page accepts the narrower reading and records it; universe states the requirement explicitly.

Only paginated commands with a countable universe are ever refused. A -k in hybrid-search or recall bounds a ranking rather than paging a table, so the top-k IS the answer and filtering it is legitimate.

allow_unknown_keys: bool

GAP-SG-202: accept a --select / --filter / --sort / --dedupe-by key that this envelope carries nowhere.

Without it such a key is refused with exit 2, because an unresolvable key produces an empty answer indistinguishable from missing data — a typo reads as “the memory does not exist”. With it the pre-v1.2.6 behaviour is restored for callers who genuinely probe a heterogeneous payload.

use_active: bool

GAP-SG-207: accept the ambient database target for a verb that changes durable state.

A mutating subcommand normally has to name its target with --db, and is refused with exit 2 when it does not. This is the explicit dispensation the Explicit Target Designation rule requires beside that requirement: the inheritance still happens, but a human asked for it and the envelope records that they did, so it is a decision rather than an accident.

max_items: Option<usize>

GAP-SG-142: emit at most N result elements.

Distinct from the per-subcommand --limit and from -k, which bound the query; this bounds only what is written to stdout, after filtering. Precedence: this flag > XDG agent_surface.max_items > 0 (no cap).

The name is not a stylistic choice and no --limit alias is offered: eight subcommands (related, pending, pending-embeddings, list, export, embedding, graph entities, enrich) already declare their own --limit, and a global argument sharing that long flag would give clap two definitions for one name inside those subcommands.

Applies to EVERY array in the envelope, not only the primary one: an agent asking for two nodes must not be handed sixty thousand edges alongside them. --select stays on the primary array — see the module documentation of crate::agent_surface for why projecting a heterogeneous secondary array would erase it rather than shrink it.

sort: Option<String>

GAP-SG-142: sort result elements ascending by this key (dotted path).

Numbers compare numerically, everything else as text. Elements without the key keep their relative order at the end of the list.

dedupe_by: Option<String>

GAP-SG-142: drop later result elements repeating this key’s value.

Elements lacking the key are always kept, since they were never proven duplicate.

count_only: bool

GAP-SG-142: replace the payload with {"count": N}.

N is the number of result elements left after --filter, --dedupe-by and --max-items.

GAP-SG-201, and this CHANGED the exit code in v1.2.8: over a paginated command whose limit actually cut rows, this is now refused with exit 2 rather than answering a page count that reads as the inventory. Declare --filter-scope page to accept the narrower reading, and the count_scope field of the agent-surface record then reports page instead of matched. A top-k bound is never refused: the k IS the answer.

GAP-SG-209: refused with exit 2 on export and ingest, which emit one record per line. A count applied there ran once per line and answered about a single record instead of the stream.

GAP-SG-206: after a subcommand that actually persists, the knob is SUPPRESSED rather than honoured, and the count_only_suppressed field of the agent-surface record says so. Replacing a write envelope with a number would discard memory_id and entities_created for an operation that already happened and cannot be replayed.

truncate_content: Option<usize>

GAP-SG-142: shorten every string longer than N characters.

Counts characters, never bytes, so a UTF-8 sequence is never split. Truncation is recorded under agent_surface.content_truncated and raises the top-level truncated flag. Precedence: this flag > XDG agent_surface.truncate_content > 0 (disabled).

max_output_bytes: Option<usize>

GAP-SG-142: cap the serialized envelope at N bytes.

Enforced by dropping trailing result elements until the payload fits — never by slicing the JSON text, which would not parse. What was dropped is recorded under agent_surface.output_truncated / dropped. Precedence: this flag > XDG agent_surface.max_output_bytes > 0 (no ceiling).

GAP-SG-209: refused with exit 2 on export and ingest. A byte budget spent once per emitted line is not a budget on the output.

no_input: bool

Refuse to read stdin anywhere in this invocation.

The refusal is declarative, not emergent: without the flag, a stdin path only fails once the read is attempted (immediately on a TTY, after the deadline otherwise). With it, --body-stdin, --graph-stdin, remember-batch and every other stdin reader fail up front with exit 1 (AppError::Validation), even when a pipe is attached and would have supplied data.

Precedence: this flag > XDG cli.no_input > false.

command: Option<Commands>

Subcommand to execute.

Implementations

impl Cli

pub fn validate_flags(&self) -> Result<(), String>

Validates concurrency flags and returns a localised descriptive error if invalid.

Requires that crate::i18n::init() has already been called (happens before this function in the main flow). In English it emits EN messages; in Portuguese it emits PT.

Trait Implementations

impl Args for Cli

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

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

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

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

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

impl CommandFactory for Cli

fn command<'b>() -> Command

Build a Command that can instantiate Self.

fn command_for_update<'b>() -> Command

Build a Command that can update self.

impl FromArgMatches for Cli

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( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Parser for Cli

fn parse() -> Self

Parse from std::env::args_os(), exit on error.

fn try_parse() -> Result<Self, Error>

Parse from std::env::args_os(), return Err on error.

fn parse_from<I, T>(itr: I) -> Self

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, exit on error.

fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, return Err on error.

fn update_from<I, T>(&mut self, itr: I)

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, exit on error.

fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, return Err on error.