status

What It Does

status prints the current repository state that matters to RAGit: branch, HEAD, exact current-HEAD snapshot readiness, runtime support, backend, historical manifest count, knowledge readiness, event-ledger activity, embedding/store/cache state, and security posture.

When To Use / When Not To Use

When to use it

You want a quick operational snapshot of the current repository.
You want to confirm whether the store is loaded and whether retrieval should be ready.
You want to inspect config surfaces without opening files manually.

When not to use it

You want a deeper health diagnosis. Use doctor.
You want to change config values. Use config set.

Syntax

pnpm ragit status [--format text|json|both] [--cwd <path>]

Arguments And Options

--format text|json|both: Choose human text, JSON, or both.
--cwd <path>: Run against another repository.

Input And Output Contract

There is no positional input and no JSON payload input.
JSON output includes branch, head, snapshot, runtime, backend, zvec, supported_types, docsAuthority, knowledge, events, manifests, embedding.configured, embedding.store, embedding.cache, embedding.ready, embedding.needsMigration, security, and format.
runtime reports the current and minimum Node versions, the current platform/arch, the two supported native targets, and aggregate supported state.
snapshot.status is missing when HEAD or its exact manifest is absent, invalid for malformed/mismatched/future manifests, store-unavailable for a valid exact manifest without a usable canonical store, and indexed only when both exact manifest and store are usable.
zvec.searchReady and knowledge.durableReady are true only for snapshot.status: indexed. The manifests count is historical context and an unrelated manifest never makes the current HEAD ready.
embedding.cache reports enabled, dir, namespaceId, entryCount, batchPolicy, retryPolicy, writable, and namespaceReadable.
security reports maskingConfigured, remoteEmbeddingPolicy, providerEgressClass, outputRemasking, quarantineEntries, lastAuditAt, and legacyUnsafeState.
Agents should usually call --format json.

Examples

Human terminal flow:

pnpm ragit status

Agent-oriented flow:

pnpm ragit status --format json

Failures And Cautions

status is a summary, not a repair command.
status exits successfully for all four snapshot diagnostic states and does not call an embedding provider to determine readiness.
Detached HEAD is reported with branch: null; an unborn repository uses head: null. Dirty worktree metadata does not invalidate an otherwise usable committed snapshot.
A loaded store does not guarantee that your exact current HEAD is indexed. Commit intended document changes, then run ingest.
Event counters reflect append-only operational ledger activity, not snapshot semantic deltas. Use timeline when you need the detailed time axis.
When embedding.needsMigration=true, change the store with migrate embeddings before running write paths against the new provider contract.
When embedding.cache.enabled=false while cache is expected, inspect doctor for embedding.cache-dir and embedding.cache-namespace.

status

On this page