Enum Command 

pub enum Command {
    Status,
    Entity(Args),
    Relations(Args),
    Search(Args),
    List(Args),
    Context(Args),
    Overview(Args),
    Type(Args),
    Health(Args),
    Due(Args),
    Gates(Args),
    Export(Args),
    Init(InitArgs),
    Quickstart(Args),
    Install(Args),
    Uninstall(Args),
    VerifyAnchors(Args),
    Publish(Args),
    Unpublish(Args),
    Domain {
        action: DomainAction,
    },
    Admin {
        action: AdminAction,
    },
    Login(Args),
    Logout(Args),
    Create(Args),
    Update(Args),
    Relate(Args),
    Delete(Args),
    Rename(Args),
    Retype(Args),
    BatchUpdate(Args),
    BatchCreate(Args),
    BatchRelate(Args),
    Recover(Args),
    Anchors(Args),
    Conflicts(Args),
    Changes(Args),
    Check(Args),
    ReviewMark(Args),
    Reload(Args),
    Fetch(FetchArgs),
    Pull(PullArgs),
    Push(PushArgs),
    BranchReset(BranchResetArgs),
    Mem {
        action: MemAction,
    },
    MemRepo {
        action: MemRepoAction,
    },
    Workspace {
        action: WorkspaceAction,
    },
    Schema(Args),
    Projection(Args),
}

Variants

Status

Node / edge counts, schema distribution, and per-binding projection state.

Entity(Args)

Read one entity as markdown.

Relations(Args)

List typed edges for an entity.

Search(Args)

Find entities by text or graph proximity.

List(Args)

Filter entities by metadata (no text match — use search for that).

Context(Args)

Read an entity’s community cluster.

Overview(Args)

All clusters with summaries and member lists. The full build renders the same rich content the MCP memstead_overview tool emits — both surfaces share the engine composer in memstead-engine.

Type(Args)

Describe one type, or list all types when no name given.

Health(Args)

Health summary (orphans, stubs, stale entities, missing fields).

Every report carries a verdict-coverage line with three buckets: examined names the axes the defect verdict answers for (a finding there fails --strict); advisory names the axes the report renders, always or on --include, beside the verdict without folding them in (stale entities, conformance findings, anchor drift, check states: the figures are shown, the verdict says nothing about them); not_examined names the axes this surface never looks at, which another surface answers for.

Due(Args)

Render the due-brief: open entities whose schema-declared due date falls inside the window (default 90d), overdue first.

Gates(Args)

Render the gates brief: the standing of every schema-declared gated transition — closed and open entities per gate, related-check coverage, open entities in dependency order.

Export(Args)

Export a mem: markdown in place, a portable .mem archive, JSON, one self-contained HTML page, or one agent-readable Markdown document (llms-txt).

Init(InitArgs)

Initialise a filesystem mem in the current (or named) folder. Strict: errors out when the target is not empty.

Quickstart(Args)

One-command cold start: workspace + default-schema mem + seed entity + MCP wiring for your agent(s), in the current (or named) folder. Tolerates dotfiles and README-grade files; derives the mem name from the folder. For the strict, script-safe variant use memstead init. Restart the agent session afterwards: a session that is already running does not attach an MCP server added while it runs.

Install(Args)

Install a sealed .mem mem — either a local file, or <scope>/<name> from the memstead.io registry. Registers it as a workspace-level read-only mount; memstead uninstall is the symmetric removal. Works on every workspace shape: a read-mem attaches to the workspace, not to one of your mems.

Uninstall(Args)

Remove an installed read-mem’s workspace-level mount. The global cache copy survives by default; re-install re-registers it. Works on every workspace shape, symmetric with install: a workspace that can attach a read-mem can detach one.

VerifyAnchors(Args)

Verify every anchor in a mem against its declared source — the standalone drift statement, no binding required. Mutates no entity, but records its findings store like any verify run.

Publish(Args)

Publish a .mem archive to the registry. Triggers GitHub Device Flow on first use; subsequent runs are silent.

Unpublish(Args)

Unpublish (hard-delete) <scope>/<name> from the registry. Permitted to the original uploader and to admins. The same <scope>/<name> becomes immediately re-publishable.

Domain

Domain-authority publishing: generate the signing key for a domain you control and print the .well-known manifest to host. publish --scope <domain>:<handle> then signs with that key — no GitHub account needed.

Fields

action: DomainAction

Admin

Admin-only registry moderation: take a mem down or deny-list bytes. Gated server-side by the MEMSTEAD_ADMINS allowlist; every action is recorded in the registry’s append-only audit log.

Fields

action: AdminAction

Login(Args)

Authenticate with a registry via GitHub Device Flow. Optional — publish auto-triggers the same flow on first use.

Logout(Args)

Remove stored credentials for a registry.

Create(Args)

Create a new entity. Provide --title, --type, and the required section fields, or pass --from <file.json> with the full payload.

Update(Args)

Modify an existing entity. --expected-hash is required for an update that changes content, unless --auto-hash (refetch before write) or --force (skip check) is given; an anchors-only update needs none, since anchors sit outside the content hash.

Relate(Args)

Add or remove a typed relationship between two entities.

Delete(Args)

Delete an entity. Use --dry-run to preview impact first. Delete is hashless by design (no post-state to race on); race protection comes from HAS_INCOMING_REFS — and RESIDUAL_STUB_FOR_READONLY_REFERRERS for read-only-referrer cases.

Rename(Args)

Rename an entity (changes ID, file path, and every incoming wiki-link).

Retype(Args)

Change an entity’s type in place (id, path and incoming edges stay; sections, metadata and every edge are validated against the target type).

BatchUpdate(Args)

Update many entities in one atomic call. Input is a JSON file with a top-level updates: [...] array (one entry per entity, each with its own hash mode and mutation fields). All-or-nothing: if any entry fails (validation, hash mismatch, missing entity) the whole batch is refused and NOTHING is committed — fix the named entry and resubmit. On success the batch lands as one commit. Mirrors memstead update per entry. MEM-REPO WORKSPACES ONLY — refuses with UNSUPPORTED_WORKSPACE_SHAPE on the filesystem-mem workspace memstead quickstart produces; fall back to one memstead update per entity there.

BatchCreate(Args)

Create many entities in one atomic call. Input is a JSON file with a top-level creates: [...] array — each entry the same shape as create --from, with its own provenance note. Intra-batch references resolve as real targets (cycles included where the schema permits), so a mutually-referencing set lands in a single pass with no stubs. All-or-nothing: any invalid entry refuses the whole batch and names EVERY failing entry. One commit per touched mem. MEM-REPO WORKSPACES ONLY — refuses with UNSUPPORTED_WORKSPACE_SHAPE on the filesystem-mem workspace memstead quickstart produces; fall back to one memstead create per entity there (losing atomicity and intra-batch reference resolution).

BatchRelate(Args)

Apply many edge changes in one atomic call. Input is a JSON file with a top-level relates: [...] array mixing additions and removals, applied in order — each entry mirrors relate (from / rel_type / to, optional remove, description, per-entry note). All-or-nothing: any invalid entry refuses the whole batch and names EVERY failing entry. One commit per touched mem. MEM-REPO WORKSPACES ONLY — refuses with UNSUPPORTED_WORKSPACE_SHAPE on the filesystem-mem workspace memstead quickstart produces; fall back to one memstead relate per edge there.

Recover(Args)

Apply parse-time-drift recovery across writable mems. Walks PARSED_RELATION_INVALID warnings, re-renders affected source entities to drop the stale rows, and reports per-entry outcomes. Read-only-origin drops surface as skipped.

Anchors(Args)

Read provenance anchors (E3a): memstead anchors <id> lists an entity’s anchors + composition; memstead anchors --artifact <path> reverse-looks-up every entity whose anchor references that path (the query the check-realization hook consumes).

Conflicts(Args)

List and resolve git merge conflicts in folder-backed mems — the one sanctioned repair when a merge in the user’s repo writes conflict markers into entity files. conflicts list shows conflicted entities; conflicts resolve <id> --side ours|theirs keeps one side, validated before it lands and committed as an attributed mutation.

Changes(Args)

Report a mem’s changes since a cursor. The cursor is backend-specific and is never a mutation’s write_id: on a git-branch mem pass a commit SHA (the head a prior call returned, or the canonical empty-tree hash 4b825dc642cb6eb9a060e54bf8d69288fbee4904 for a first sync); on a folder mem pass an RFC3339 timestamp (the ts of the last ledger entry you read, or empty for a first sync).

Check(Args)

Record a check: “entity E checked, verdict ok | failed, via method M” — an engine-recorded act carrying the session’s --role, never a mutation (entity markdown, hash, and mem commits untouched). Derived check state serves via memstead entity <id> --provenance.

ReviewMark(Args)

Read and move the per-mem review mark — the engine’s one pointer per mem to the last human-approved state. list shows every mem’s mark and head; set/clear move it (explicit target only); diff reports the unreviewed delta. Marks never gate writes.

Reload(Args)

Reload one writable mem’s slice of the in-memory store from its on-disk branch tip — or every writable mem when --mem is omitted. CLI parity with the MCP memstead_reload tool.

Fetch(FetchArgs)

Fetch a mem’s branch refs from a git remote into the mem-repo (no local branch moves — inspect first, then pull). Requires a git-branch-backed mem (INVALID_INPUT on folder mounts); refuses UNKNOWN_REMOTE when the remote is not configured.

Pull(PullArgs)

Fast-forward a mem’s branch to its fetched remote counterpart and reload the in-memory store. Refuses LOCAL_DIVERGENCE when the local branch is not an ancestor of the remote — reconcile via branch-reset, or resolve on another clone and push.

Push(PushArgs)

Push a mem’s branch to a git remote. --force uses force-with-lease semantics; without it, non-fast-forward pushes refuse (NON_FAST_FORWARD). Refuses UNKNOWN_REMOTE when the remote is not configured. --all pushes every mounted git-branch mem’s branch plus the workspace’s schema-and-config ref, fast-forward only: silent for refs already in sync, one line per ref moved, a refused ref named while the others still go, non-zero exit at the end.

BranchReset(BranchResetArgs)

Reset a mem’s branch pointer to a target ref/SHA. Refuses to discard commits reachable from any remote ref (PUSHED_COMMITS_PROTECTED).

Mem

Mem lifecycle commands.

Fields

action: MemAction

MemRepo

Mem-repo-git lifecycle commands.

Fields

action: MemRepoAction

Workspace

Introspect and configure workspace policy — dump reads the effective config; allow-create/revoke-create/allow-delete/ revoke-delete/grant-cross-link/revoke-cross-link/set-mutations write the mem-lifecycle allowlist, cross-mem link grants, and mutation policy.

Fields

action: WorkspaceAction

Schema(Args)

Author-time schema tooling. memstead schema validate <path> checks a schema package directory against the engine’s loader without touching a workspace.

Projection(Args)

Pipeline tooling — one versioned v2 binding per pipeline, sources inline. Nine verbs: brief renders a binding’s run-brief (the Markdown prompt an agent consumes); init scaffolds a fresh v2 record non-interactively; migrate converts every prior on-disk generation (gen-1 root folders, the four-primitive store, the v1 three-file store) into v2 records in place; enable <build|sync|verify> <binding> adds a missing operation block; edit patches a binding’s author-editable fields; advance records disposition-gated sync-baseline advances; exclude records authored exclusions for in-scope artifacts; verify measures a binding’s fidelity and records findings; check-path answers deny verdicts for paths and patterns.

Implementations

impl Command

pub fn verb(&self) -> &'static str

The subcommand’s user-facing verb name, as typed on the command line — the verb field the friction ledger records on a typed refusal. Nested action groups report their top-level noun (mem, mem-repo, workspace, domain, admin): per-verb counts at that granularity already answer the design questions, and nothing payload-shaped can leak through a static name.

Trait Implementations

impl Debug for Command

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

Formats the value using the given formatter.

impl FromArgMatches for Command

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 Command

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