Browse documentation
CLI and agent interfaces
Command forms for libraries, source graphs, actors and code evidence.
The executable is effectful. Angle-bracket values below are placeholders. Use the commands supported by your runtime version.
Libraries
effectful new <directory> --kind library [--name <name>]
effectful verify <library-project>
effectful test <library-project>
effectful test <library-project> --consumer <name> --case <case>
effectful test <library-project> --cache <directory> --explain-reuse
new needs an empty/absent destination and a recorded source commit in the binary. library.toml names the consumers. Verification runs no tests. Selecting one case tests only that case. Keep the cache directory outside the source project. --no-cache requests fresh execution.
Consumer watch
effectful serve --app <library-project> --consumer <name> \
--state <directory> --watch
serve.toml defines loopback routes. The command prints listener graph <host:port> and watch events. Compatible tested candidates can activate; refused edits retain the accepted selection. See watch instructions.
Source graphs
effectful graph check <application>
effectful graph test <application> [--case <case>]
effectful graph test <application> --no-cache --evidence <new-file> --format json
A graph is the application and source libraries. Graph tests use scripted in-memory execution, not live external integration.
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 initializes the behaviour; cast submits a message. graph state reads supported receive state, not an arbitrary pending/ended run. inspect reports source-connected execution state. Preserve node history and retained code together.
Code and evidence
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 returned IDs. context gives bounded relationships; show includes the body. Continuations belong to their checked inputs/query. Depth limits and pagination are separate.
code evidence checks applicability without running tests.
Diagnostics and MCP
effectful explain <diagnostic-code> --format json
effectful mcp
The client manages the MCP stdio process. Tools come from the implemented operation table and retain structured refusals.
Structured operations use ops/v1; code-query cards use code/v1. Follow the returned schema. JSON flags are operation-specific; serving and MCP use their own transports.