15 cli and api

CLI and API

Fractalflow.exe is both the GUI and a CLI. If the first argument is a known verb, the process skips WPF, attaches to the parent console, runs the command, and exits — except api, which stays running as an HTTP server.

The CLI and API operate on the same saved objects as the UI: hearted params, compositions, render output, Clip Studio exports, Resources settings, Auto jobs, procedural projects.

Automatable GUI workflow:

Explore → Seed fine tune → Compose → Render → Clip Studio

Procedural workspaces have a parallel path:

Videos (Psychedelia Live / Generator Lab / Shader Lab) → Render final output → Video library → Clip Studio

API Lab: a successful local version request and HTTP 200 response.

Invoke the published exe (or dotnet run --project src\Fractalflow.App -- <verb> ... from a dev tree). Examples below use fractalflow as the command name. From the folder containing the portable executable, define this session-only PowerShell alias first:

Set-Alias fractalflow (Resolve-Path .\Fractalflow.exe).Path

Alternatively replace fractalflow with .\Fractalflow.exe in each command. The captured CLI help is a plain-text reference from this build. Replace <id> placeholders with actual IDs; angle-bracket placeholders are not PowerShell syntax. JSON filenames represent input files you must supply or export, not files automatically created by invoking the command.

Global flag: --json — machine-readable JSON on stdout (NDJSON for streaming verbs).

fractalflow help
fractalflow version --json

catalog

Discovery of every picker the UI uses.

fractalflow catalog formulas --json
fractalflow catalog formulas --family "KIFS folded 3D" --json
fractalflow catalog seed-presets --formula-id 101 --json
fractalflow catalog seed-timeline-modes --json
fractalflow catalog seed-local-motion-modes --formula-id 101 --json
fractalflow catalog source-seed-animation-timing-modes --json
fractalflow catalog tracks --formula-id 101 --json
fractalflow catalog family-packs --json
fractalflow catalog layer-blend-modes --json
fractalflow catalog layer-key-modes --json
fractalflow catalog flight-mix-modes --json
fractalflow catalog final-video-formats --json
fractalflow catalog video-qualities --json
fractalflow catalog clip-export-formats --json
fractalflow catalog clip-effects --json
fractalflow catalog clip-event-kinds --json
fractalflow catalog recipes --json
fractalflow catalog camera --json
fractalflow catalog visual --json

fractalflow automation capabilities --json is the Auto Builder capability snapshot (limits, engines, quality profiles).

params and compositions

Seeds in the SQLite library (data\fractalflow.db):

fractalflow params random --count 12 --seed 42 --json
fractalflow params list --status hearted --json
fractalflow params get <id> --json
fractalflow params save-file .\seed.json --json
fractalflow params heart <id> --json
fractalflow params unheart <id> --json
fractalflow params mutate <id> --strength 0.4 --seed 7 --json

Compositions:

fractalflow compositions list --json
fractalflow compositions get "<name-or-id>" --json
fractalflow compositions save-file .\flight.json --json
fractalflow compositions delete "<name-or-id>" --json

render

Native HLSL/CPU render of a saved composition (same pipeline as the Render tab).

fractalflow list-renderers
fractalflow render "<name-or-id>" --out <dir> --width 1920 --height 1080
fractalflow render "<name-or-id>" --no-mp4
fractalflow render "<name-or-id>" --renderer hlsl
fractalflow render "<name-or-id>" --cores 8
fractalflow render --param-id 5 --still --out D:\stills
fractalflow render --params-file .\seed.json --frames 120 --fps 30 --keep-images
fractalflow render "My Flight" --json

--json streams NDJSON progress events. Existing PNG frames are reused on retry.

clips

Clip Studio export without opening the GUI.

fractalflow clips effects --json
fractalflow clips events --json
fractalflow clips probe .\output\flight_id0042\flight.mp4 --json
fractalflow clips export .\output\flight_id0042\flight.mp4 --speed 0.5 --format mp4 --quality high --json
fractalflow clips export .\output\flight_id0042\flight.mp4 --ping-pong --format mp4 --quality archive --json
fractalflow clips export .\output\flight_id0042\flight.mp4 --ping-pong --output-trim-start 1.5 --output-trim-end 4.0 --format mp4 --quality archive --json
fractalflow clips export .\output\flight_id0042\flight.mp4 --effect hue-cycle --event 2.5:glitch-hit:0.2:0.8:drop --json

--trim-start / --trim-end select seconds on the original source. --output-trim-start / --output-trim-end cut after speed, effects, and ping-pong (the same final-cut path Clip Studio uses when the rendered preview range is trimmed).

library list-videos lists rendered MP4s across tracked roots. library delete-dir <p> deletes an entire render directory.

automation

Classic Auto Builder, same bodies as /v1/automation/*.

fractalflow automation capabilities --json
fractalflow automation seed-plan --request .\manual\examples\automation\fold-dive-kifs.json --json
fractalflow automation composition-plan --request .\manual\examples\automation\fold-dive-kifs.json --json
fractalflow automation clip-job --request .\manual\examples\automation\fold-dive-kifs.json --json

Use a foldDive style when the goal is a KIFS/Mandelbox-like/quaternion/path-traced fold traversal. The planner filters to formulas with starter templates, prefers true 3D formulas, chooses formula-aware 3D camera presets, and adds structural parameter tracks where supported.

procedural

Videos procedural engines (Psychedelia Live, Animation Lab, Shader Lab) and procedural Auto.

fractalflow procedural modules --json
fractalflow procedural auto capabilities --json
fractalflow procedural auto plan --request .\procedural-auto.json --variant 4 --out .\plan.json --json
fractalflow procedural auto render --request .\procedural-auto.json --variant 4 --json
fractalflow procedural auto batch --request .\procedural-auto.json --variant 4 --count 8 --json
fractalflow procedural create --module shader-lab --source standard-plasma --seed 42 --frames 180 --out .\shader-project.json --json
fractalflow procedural preview .\shader-project.json --frame 45 --out .\preview.png --json
fractalflow procedural transform .\shader-project.json --operation motion --options .\transform-options.json --locks .\locks.json --out .\shader-motion.json --json
fractalflow procedural quick-create --seed 42 --variant 4 --out .\quick-shader.json --json
fractalflow procedural render .\shader-project.json --format h264Mp4 --keep-frames --json

procedural auto plan is side-effect free. render and batch stream job events, cancel on Ctrl+C, publish through the same Videos library path as the UI/API, and make retained PNG-only output available to Clip Studio without an MP4 placeholder.

Omitted output options inherit the Resources tab without changing it.

Also: procedural import-shadertoy and procedural import-url for the same Safe Mode imports as Shader Lab.

api

Long-running HTTP server. REST under /v1/* mirrors every CLI verb. SSE for render progress.

fractalflow api --port 8080 --bind 127.0.0.1
fractalflow api --port 8080 --bind 0.0.0.0 --token "replace-with-a-long-random-secret"

The second form is the explicit LAN listener. Keep bearer authentication enabled and put the service behind a VPN or TLS reverse proxy on untrusted networks. --no-auth exists for local experiments; do not use it on a shared network.

Point API Lab Base URL at this server and paste its startup bearer token into Bearer token. The first command generates a token automatically; leaving API Lab authentication blank produces HTTP 401.

resources and settings

Same keys as the Resources tab:

fractalflow resources list --json
fractalflow resources set-gpu 0 off --json
fractalflow resources set-concurrency 6 --json
fractalflow settings list --json
fractalflow settings set finalRenderVideoFormat losslessMkv --json
fractalflow settings set clipStudioPreviewProfile balanced --json
fractalflow settings set clipExportVideoQuality archive --json
fractalflow settings set finalRenderVideoQuality archive --json

templates and version

fractalflow templates list --json
fractalflow templates get 0 --json
fractalflow version --json

version is the handshake: app version, paths, renderer availability.

JSON payloads

To save an editable composition body from an existing saved ID, use the plain output form (without --json, which adds an {ok,data} envelope):

fractalflow compositions get 42 | Set-Content -Encoding utf8 .\flight.json

Replace 42 with an ID from compositions list. Keep the matching source library/assets when moving this file to another installation.

Request file shapes, seedAnimationProfile, blend/key fields, /v1/clips/export, GPU selection, slow-render notes, preview vs final, portable dependencies, path-traced behavior, and 2D/3D family notes are in the bundled API/CLI payload reference. Seven complete native Auto request examples are included under examples/automation. Run the request examples from the repository root, or adjust paths to the downloaded manual folder. For seed.json use Copy JSON on an Explore seed; for flight.json export a saved composition with the CLI. Procedural project and transform payloads are described in the bundled reference; replace illustrative filenames with your own files.

Continue: Files and recovery.