CLI and agent interfaces

The executable is currently named effectful. The forms below cover the routes used by these docs. Angle-bracket values are placeholders, not literal shell input. Use commands and examples that match the installed runtime version.

Library projects

effectful new <directory> --kind library [--name <name>]
effectful verify <library-project>
effectful test <library-project>
effectful test <library-project> --consumer <name> --case <case>

new requires an empty or absent destination and a binary with a recorded source identity. library.toml identifies the project and its declared consumers. Verification does not execute the test cases. A selected test result has only the selected scope.

Library consumer watch

effectful serve --app <library-project> --consumer <name> \
  --state <directory> --watch

The consumer’s serve.toml defines its loopback routes. The command prints listener graph <host:port> and watch events. Compatible tested candidates can become active; refused edits leave the last accepted selection serving. Use the watch guide for request and stop commands.

Source graphs

effectful graph check <application>
effectful graph test <application> [--case <case>]
effectful graph test <application> --no-cache --evidence <new-file> --format json

Here, a graph is the application and its source libraries. Graph tests use a scripted in-memory runner. They are distinct from the temporal graph database and from a live external integration test.

Durable actors

effectful graph spawn <application> --state <directory> \
  --behavior <name> --key <text> --init <state.json>
effectful graph cast --state <directory> --run <run-id> --message <message.json>
effectful graph state --state <directory> --run <run-id>
effectful inspect <run-id> --state <directory>

spawn creates the behaviour with its initial state. cast submits a message. graph state reads a behaviour at its supported receive state; it is not an unrestricted read of a pending or ended run. inspect reports the source-connected execution state.

The state directory must belong to the intended node. Preserve its history and retained code together.

Code discovery and context

effectful code find <application> --query <text> --format json
effectful code context <application> --id <definition-id> --depth <n> \
  --expected-snapshot <snapshot> --format json
effectful code show <application> --id <definition-id> \
  --expected-snapshot <snapshot> --format json
effectful code dependents <application> --id <definition-id> --depth <n> --format json
effectful code evidence <application> --receipt <file> --format json

Use identities returned by discovery, not names guessed from the source. context gives a bounded relationship view; show includes a body. A continuation token belongs to the checked inputs and query that produced it. A depth limit is separate from pagination.

code evidence compiles the current inputs and checks applicability without executing cases.

Diagnostics and MCP

effectful explain <diagnostic-code> --format json
effectful mcp

MCP runs over stdio. The client starts and manages the process. Available tools come from the landed operation table and preserve the operation’s structured refusal rather than translating every error into an unstructured string.

Supported structured operations return an ops/v1 envelope; code-query cards use their code/v1 schema. Follow the schema returned by the operation rather than assuming all JSON has the same shape.

JSON formatting is operation-specific. A command supporting --format json does not imply that every CLI command accepts that flag. Long-lived operations such as serving and MCP have their own transports.