CLI reference

Entry point: ./src/runtime/cli.ts (bundled to dist/cli.js → guildhall bin).

The CLI talks to the same local service and project files as the browser UI. Use it for local service lifecycle, project registry management, and focused debug runs. Task creation, approval, and setup interviews live in the browser UI and HTTP API rather than as separate human-facing CLI commands.

guildhall init [path]

Open the setup flow for a project. The default path launches the browser setup wizard; completing that flow creates ./guildhall.yaml and registers the project.

Flags:

• --port <n> (default 7777) — local service / browser UI port.
• --no-browser — don't auto-open the browser.
• --cli-wizard — use the text wizard instead of the web one.
• --no-serve — with --cli-wizard, write ./guildhall.yaml and register the project without launching the web wizard. Without --cli-wizard, Guildhall still serves the browser setup flow.

guildhall register <path>

Register an existing project (must contain ./guildhall.yaml) in ~/.guildhall/registry.yaml.

guildhall unregister <id|path>

Remove a project from the registry. Does not delete ./memory/ or ./guildhall.yaml.

guildhall list

Print all registered projects with id, name, and absolute path.

guildhall run [id|path]

Run the orchestrator. Blocks until Ctrl-C or no work remains.

Flags:

• --domain <id> — only tick this one coordinator domain.
• --max-ticks <n> — stop after N ticks. For testing.
• --one-task — stop after one task reaches a terminal, PR, or blocked handoff.

guildhall serve [path]

Ensure Guildhall is running locally, then open the browser UI.

Flags:

• --no-open — don't open a browser.
• [path] — optional project path hint to open directly.

guildhall start

Start the local Guildhall service in the background.

This is the daemon-style path when you want the service to keep running without holding open the current terminal.

guildhall open [path]

Open the running service in a browser. If the service is not already running, Guildhall starts it first.

Flags:

• [path] — optional project path hint used when the service needs to start.

guildhall stop

Stop the background Guildhall service.

guildhall config [id|path]

Re-run the setup wizard against an existing project.

Examples

guildhall init ~/projects/my-app
guildhall run my-app --domain ui
guildhall serve