CLI reference

The fractal CLI reads and updates the graph from your shell, scripts, and coding agents. For a graphical client, use the web app.

fractal --help
fractal help --all
fractal agents --help
fractal missions start --help

Use the installed build's help for exact flags, required arguments, and actor rules. --json returns structured output where supported. Current lists focus on active state; use each command's history options for finished work.

Everyday work

Command	Purpose
`fractal now`	Understand what needs action.
`fractal agents ls`	Inspect agents and readiness.
`fractal agents show ID`	Inspect one agent's current state.
`fractal agents queue ID`	Inspect its ordered runs.
`fractal missions ls`	List missions and current work.
`fractal missions show ID`	Inspect a definition or run.
`fractal work ls`	Inspect ready and active steps.
`fractal alerts ls`	List requests and approvals.
`fractal conversations`	Read and send durable conversation.
`fractal usage`	Inspect observed usage and estimated cost.

Publication and planning

fractal apply FILE --as ACTOR --dry-run previews KDL without publishing. Omit --dry-run to publish it. fractal missions start creates a run; publishing a definition does not start it. fractal launch creates and reviews a planner-backed candidate.

For small independent authorized work, use fractal work start. Claim before executing assigned work, record progress, and complete with evidence. Use fractal work revise for an explicit new generation of an existing run.

Operating a machine

Command	Purpose
`fractal setup`	Configure identity, integrations, and startup.
`fractal doctor`	Check daemon and runtime dependencies.
`fractal service status`	Inspect the user service.
`fractal fleet status`	Inspect fleet membership.
`fractal replication status`	Inspect graph synchronization.
`fractal devices`	Pair, inspect, and revoke clients.
`fractal subject show ID`	Inspect one typed graph subject.
`fractal demo check FILE`	Validate a scripted demo file without playback.
`fractal web`	Open the configured, already running web app; does not start a server.

fractal up runs the foreground daemon for explicit process supervision. Do not launch it alongside another daemon using the same state. Prefer setup's user service for ordinary installations.

Identity and automation

Use --as person/NAME where a person operation requires an actor. A managed agent uses its bound identity; a flag is not permission to impersonate someone. Person-only setup and scripted demos must run outside a bound agent session.

See Configuration and KDL, the CLI implementation, and the web URL launcher for the command contracts.