entity CLI reference | Entity RuntimeEvery command and option of the entity command, generated from its clap definition.Entity Runtimereferenceentity-runtimereferenceadopterdeveloperreference

entity

ReferenceEntity Runtime

ForAdopter · Developer

Source & revision

entity-runtime/website/docs/reference/cli.md · 763e104efd1f

Generated by entity-runtime-docs from the clap definition in crates/entity-cli/src/cli.rs. It lists only commands that exist. entity --version prints the version, and --help after any command prints the text below.

Schema-driven entity runtime: validate definitions, create instances, execute operations.

An entity type is a YAML document — schema, lifecycle, operations, preconditions, invariants,
events. The kernel decides `definition + instance + operation + arguments -> Decision`; this
command is the shell that reads the files and prints the decision.

Values passed with --fields, --instance and --arguments are read three ways:
  inline JSON        --fields '{"title": "Login fails"}'
  @<path>            --instance @ticket.json      (JSON or YAML)
  -                  --instance -                 (standard input; JSON or YAML)
Only one flag per invocation may read standard input. A Decision printed by `create` or `execute`
can be fed straight back as an --instance.

Exit codes: 0 decided · 1 refused (or a definition is invalid) · 2 invalid invocation.

Commands

Command	What it does
entity validate	Check definitions; report every file, and exit 1 if any is invalid
entity inspect	Show what a definition declares: fields, states, rules, operations
entity graph	Draw a definition: its lifecycle, or the references between several definitions
entity create	Create an instance: definition + id + fields -> Decision
entity execute	Execute an operation: definition + instance + operation + arguments -> Decision
entity list	List what a store holds for one entity type: every identity, sorted, one per line
entity generate	Generate public surfaces from a validated definition set
entity generate docs	Write standalone HTML/Markdown docs plus OpenAPI and AsyncAPI contracts
entity generate rust-cli	Generate, compile and install a definition-specific Rust command
entity mcp	Mount stored entities as model-controlled MCP tools over standard input/output
entity store	Work with persistent stores
entity store migrate-file	Migrate a pre-0.15 File Store into the confined v2 format, out of place
entity skill	Render a compact Agent Skills document that teaches this installed CLI

entity validate

Check definitions; report every file, and exit 1 if any is invalid

Usage: entity validate <DEFINITIONS>...

Argument	Required	Repeats	Default	Meaning
<DEFINITIONS>...	yes	yes	none	Definition files, YAML.

entity inspect

Show what a definition declares: fields, states, rules, operations

Usage: entity inspect [OPTIONS] <DEFINITION>

Argument	Required	Repeats	Default	Meaning
<DEFINITION>	yes	no	none	The definition file, YAML.
--format <FORMAT>	no	no	text	How to print what the definition declares. One of text, json, yaml.

entity graph

Draw a definition: its lifecycle, or the references between several definitions

Usage: entity graph [OPTIONS] <DEFINITIONS>...

Argument	Required	Repeats	Default	Meaning
<DEFINITIONS>...	yes	yes	none	The definition files, YAML. Several are only useful with --references.
--references	no	no	none	Draw the references between the definitions instead of one definition's lifecycle: entity types as nodes, ref fields as the edges between them.
--format <FORMAT>	no	no	text	How to draw it. One of text, mermaid, dot, svg, html.

entity create

Create an instance: definition + id + fields -> Decision

Usage: entity create [OPTIONS] --definition <DEFINITIONS> --id <ID>

Argument	Required	Repeats	Default	Meaning
--definition <DEFINITIONS>	yes	yes	none	The definition file, YAML. Repeat to register several types or versions at once.
--entity <ENTITY>	no	no	none	Which type to create, when several --definition files were given. Several are needed whenever a definition declares a ref: the type it points at has to be registered too, or the registry is not a consistent set. With one file this is unnecessary and the type is unambiguous.
--id <ID>	yes	no	none	The new instance's identity. The kernel generates none; you supply it.
--fields <FIELDS>	no	no	{}	The fields, as inline JSON, @<path> or - for stdin.
--store <STORE>	no	no	none	A directory to keep the result in, so the next command can find it. Without one this prints a Decision and forgets it, which is the kernel's own shape: it decides and holds nothing. With one, the decision is committed — state and events together — and execute --store can pick the instance up by id instead of being handed it back on the command line.
--record-id <RECORD_ID>	no	no	none	Caller-supplied idempotency identity for this complete decision.
--recorded-at <RECORDED_AT>	no	no	none	When this was recorded, ISO-8601. Your clock: the kernel has none.
--correlation <CORRELATION>	no	no	none	The wider flow, when there is one.
--causation <CAUSATION>	no	no	none	What immediately led to this record, when there is one.
--actor <ACTOR>	no	no	none	Who asked.
--no-actor	no	no	none	Record explicitly that no actor caused this decision.
--format <FORMAT>	no	no	json	How to print the decision. One of text, json, yaml.

entity execute

Execute an operation: definition + instance + operation + arguments -> Decision

Usage: entity execute [OPTIONS] --definition <DEFINITIONS> --operation <OPERATION>

Argument	Required	Repeats	Default	Meaning
--definition <DEFINITIONS>	yes	yes	none	The definition file, YAML. Repeat to register several types or versions at once.
--instance <INSTANCE>	no	no	none	The current instance (or a Decision holding one), as inline JSON, @<path> or -. Not needed when --store and --id say where to find it, and refused beside them: two sources for one instance would leave the caller guessing which one decided.
--store <STORE>	no	no	none	A directory holding the instance, written by an earlier create --store. The instance is loaded from it, the decision is committed back to it at the revision that was loaded, and a concurrent writer is refused rather than overwritten.
--id <ID>	no	no	none	Which instance in the store to act on.
--entity <WANTED_ENTITY>	no	no	none	Which type to act on, when several --definition files were given.
--operation <OPERATION>	yes	no	none	The operation name, as declared in the definition.
--arguments <ARGUMENTS>	no	no	{}	The arguments, as inline JSON, @<path> or - for stdin.
--expected-revision <EXPECTED_REVISION>	no	no	none	The revision of the stored instance this request was decided on. Defaults to whatever the store holds when the command runs, which is what a sequential local command wants. Pass it when retrying: an already-accepted --record-id is returned as the original record only when the retry names the same revision the first request was decided on, so a lost response can be recovered after the subject moved.
--record-id <RECORD_ID>	no	no	none	Caller-supplied idempotency identity for this complete decision.
--recorded-at <RECORDED_AT>	no	no	none	When this was recorded, ISO-8601. Your clock: the kernel has none.
--correlation <CORRELATION>	no	no	none	The wider flow, when there is one.
--causation <CAUSATION>	no	no	none	What immediately led to this record, when there is one.
--actor <ACTOR>	no	no	none	Who asked.
--no-actor	no	no	none	Record explicitly that no actor caused this decision.
--format <FORMAT>	no	no	json	How to print the decision. One of text, json, yaml.

entity list

List what a store holds for one entity type: every identity, sorted, one per line. The question create --store and execute --store could not answer: they can act on an instance whose id you already know, and nothing could say which ids there are. A shell that did not write a store has to be able to ask it what it holds before it can do anything else.

Usage: entity list [OPTIONS] --store <STORE> --entity <ENTITY>

Argument	Required	Repeats	Default	Meaning
--store <STORE>	yes	no	none	The directory an earlier create --store wrote into.
--entity <ENTITY>	yes	no	none	Which entity type to list.
--format <FORMAT>	no	no	text	How to print the identities. One of text, json, yaml.

entity generate

Generate public surfaces from a validated definition set

Usage: entity generate <COMMAND>

entity generate docs

Write standalone HTML/Markdown docs plus OpenAPI and AsyncAPI contracts

Usage: entity generate docs [OPTIONS] --definition <DEFINITIONS> --out <OUT>

Argument	Required	Repeats	Default	Meaning
--definition <DEFINITIONS>	yes	yes	none	The definition file, YAML. Repeat to register several types or versions at once.
--out <OUT>	yes	no	none	Destination directory.
--force	no	no	none	Replace this exact directory only when it carries the generator marker.

entity generate rust-cli

Generate, compile and install a definition-specific Rust command

Usage: entity generate rust-cli [OPTIONS] --definition <DEFINITIONS> --name <NAME> --out <OUT>

Argument	Required	Repeats	Default	Meaning
--definition <DEFINITIONS>	yes	yes	none	The definition file, YAML. Repeat to register several types or versions at once.
--name <NAME>	yes	no	none	Binary and Cargo package name.
--out <OUT>	yes	no	none	Installed host-platform binary path.
--runtime-source <RUNTIME_SOURCE>	no	no	.	Matching entity-runtime source checkout. Defaults to the current directory.
--build-dir <BUILD_DIR>	no	no	none	Retained generated crate. Defaults to build/entity-runtime/NAME.
--force	no	no	none	Replace only exact generator-owned build and output targets.

entity mcp

Mount stored entities as model-controlled MCP tools over standard input/output

Usage: entity mcp --definition <DEFINITIONS> --store <STORE>

Argument	Required	Repeats	Default	Meaning
--definition <DEFINITIONS>	yes	yes	none	The definition file, YAML. Repeat to register several types or versions at once.
--store <STORE>	yes	no	none	File Store v2 root used by every tool call.

entity store

Work with persistent stores

Usage: entity store <COMMAND>

entity store migrate-file

Migrate a pre-0.15 File Store into the confined v2 format, out of place

Usage: entity store migrate-file [OPTIONS] --from <V1_ROOT> --to <V2_ROOT>

Argument	Required	Repeats	Default	Meaning
--from <V1_ROOT>	yes	no	none	The legacy File Store directory. It is never modified.
--to <V2_ROOT>	yes	no	none	A destination path that does not exist.
--dry-run	no	no	none	Validate the complete migration without writing destination bytes.

entity skill

Render a compact Agent Skills document that teaches this installed CLI

Usage: entity skill [OPTIONS]

Argument	Required	Repeats	Default	Meaning
--out <OUT>	no	no	none	Write the skill to this path instead of standard output.
--force	no	no	none	Replace the explicitly named output file when it already exists.

What an eventlog-providers build adds

The tables above describe the default build, which is what the release archives and a plain cargo install contain. Building entity-cli with the eventlog-providers Cargo feature (Rust 1.91) adds the items below, read from the #[cfg(feature = "eventlog-providers")] items of the same definition. --help on such a build prints their exact flags.

Command	Adds	Meaning
entity create	--eventlog-config <EVENTLOG_CONFIG>	Eventlog File selection JSON; selects the recorded facade for --store.
entity execute	--eventlog-config <EVENTLOG_CONFIG>	Eventlog File selection JSON; selects the recorded facade for --store.
entity list	--eventlog-config <EVENTLOG_CONFIG>	Eventlog File selection JSON; selects the recorded facade for --store.
entity store	subcommand entity store provision-eventlog-file	Prepare a new recorded Eventlog File authority and print its exact reopen authority.