Browse documentation

Reference

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.

Search concepts, guides and reference.