CLI

The same binary is the server and the client of a running server. With no server to talk to it starts one; with one already up, it speaks ops to it.

usage

goofi [serve] [--port N] [--bind HOST] [--extra-nodes DIR]
      [--list-nodes] [--headless] [--debug] [--demo]

Flags

Flag	Default	Effect
`--port N`	`8000`	The port to serve on.
`--bind HOST`	`127.0.0.1`	The address to serve on. Any address reachable from other machines prints a warning, because there is no auth and /term is a real shell.
`--extra-nodes ROOT`	`none`	A folder of node files, .py and .rs, scanned after the shipped bundles and before the open patch’s own workspace. Repeatable; a later root wins a type name it shares with an earlier one.
`--list-nodes`	`none`	Print the registered node types and exit.
`--headless`	`none`	Serve the API alone: /control, /data, /term, /mcp. The app’s routes are never mounted.
`--debug`	`none`	Open /dev/*: the UI primitive gallery at /dev/ui, and the other development surfaces. Shut otherwise.
`--demo`	`none`	The mode a PUBLIC goofi serves in. It disables the terminal, agents, the filesystem, save and load, and audio. It is NOT a sandbox: a param expression is still Python.

Three flags have environment spellings: GOOFI_HEADLESS=1, GOOFI_DEBUG=1 and GOOFI_DEMO=1. Set GOOFI_HEADLESS for the build and the app is left out of the binary entirely.

Client mode

goofi <op phrase> [--json] sends one op to a running server. goofi - reads ops from stdin as one batch, which is one undo step. Every phrase is from the op vocabulary, all 57 of them, with no CLI-only verbs.

goofi node add Psd                    # one op
goofi library list --json             # …as JSON
goofi - < ops.txt                     # a batch from stdin: ONE undo step
goofi completions zsh > _goofi        # a completion script with no vocabulary of its own

goofi completions zsh|bash emits a shell-completion script that holds no vocabulary of its own: every TAB asks the running server, so the script cannot go stale against the binary.

Routes

Route	What it is
`/control`	the op vocabulary over a WebSocket, where every mutation is a command
`/data`	binary frame streams, one per (node, slot), whatever the viewer count
`/term`	a real shell
`/mcp`	goofi as an MCP server, so an agent drives the same op vocabulary
`/exec`	command execution
`/dev/*`	dev surfaces, only with --debug; /dev/ui is a gallery of every UI primitive

There is no authentication, by design. goofi is a single-user, local or trusted-LAN application: /term is a real shell, and /exec and /mcp extend the same trust /control always has. The Origin and Host allowlist is a drive-by guard, not authentication.

A goofi that strangers can reach runs in demo mode instead, which drops those ops and never mounts those routes. See Run it.

This reference describes goofi 3.1.0(537cd394), generated from a running instance on 2026-09-06.