CLI Commands

Daemon

`hatch up`

Start the Hatch daemon.

Initializes the config, generates and trusts the CA if needed, installs the DNS resolver, and creates the launchd plist. Safe to run multiple times (idempotent).

hatch up

`hatch down`

Stop the Hatch daemon and tray app.

Unloads the launchd plist, stops the daemon gracefully, and terminates the tray app if running.

hatch down

`hatch restart`

Restart the daemon and tray app (stops then starts).

hatch restart

`hatch status`

Show daemon state, project list, and service health. When a service is unhealthy, the output includes a diagnosis: whether the port is free (nothing listening) or held by another process (with process name and PID). If port conflicts are detected, a summary with suggested kill commands is printed at the end.

hatch status

`hatch logs`

View daemon logs.

hatch logs
hatch logs -f          # follow (tail)
hatch logs -n 100      # show last 100 lines

Flag	Default	Description
`-f, --follow`	`false`	Continuously stream new log entries
`-n, --lines`	`50`	Number of lines to show

Projects

`hatch add <name>`

Add or update a project.

hatch add myapp --proxy http://localhost:3000
hatch add myapp --proxy http://localhost:3000 --domain custom.test
hatch add myapp --proxy http://localhost:3000 --path ~/projects/myapp

Flag	Default	Description
`--proxy`	`http://localhost:3000`	Upstream target URL
`--domain`	`<name>.<tld>`	Override the project domain
`--path`	current directory	Project directory path

`hatch link`

Link a project using the hatch.yml file in the current directory.

cd ~/projects/myapp
hatch link
hatch link --name custom-name

Flag	Default	Description
`--name`	directory basename	Override the project name

`hatch unlink`

Unlink a project from Hatch. Removes it from the central config but does not delete the hatch.yml file.

cd ~/projects/myapp
hatch unlink
hatch unlink --name custom-name

Flag	Default	Description
`--name`	directory basename	Override the project name

`hatch list`

List all configured projects. Alias: hatch ls.

hatch list

Shows project name, domain, enabled/disabled status, and services.

`hatch remove <name>`

Remove a project from the config. Alias: hatch rm.

hatch remove myapp
hatch remove myapp -f    # skip confirmation

Flag	Default	Description
`-f, --force`	`false`	Skip confirmation prompt

`hatch enable <name>`

Enable a disabled project.

hatch enable myapp

`hatch disable <name>`

Disable a project without removing it.

hatch disable myapp

`hatch open [name]`

Open a project in your default browser.

hatch open myapp

System

`hatch init`

Initialize Hatch for first-time use. Creates ~/.hatch, generates the CA hierarchy, trusts the root CA in Keychain, and installs the DNS resolver. Does not start the daemon.

hatch init

`hatch trust`

Trust the root CA in the macOS Keychain. Regenerates the CA if it’s missing.

hatch trust

`hatch doctor`

Run diagnostic health checks. Reports on config validity, DNS resolver, CA certificates, launchd plist, port availability, and stale projects.

hatch doctor

`hatch clean`

Complete uninstall. Stops the daemon, removes the DNS resolver, untrusts the root CA, and deletes ~/.hatch and Caddy data directories. Alias: hatch uninstall.

hatch clean

Tunnels

`hatch tunnel start <project>/<service>`

Start a Cloudflare Tunnel for a service. Requires cloudflared to be installed.

hatch tunnel start myapp/web

Prints the public tunnel URL on success. For quick tunnels, the URL is a temporary trycloudflare.com address.

`hatch tunnel stop <project>/<service>`

Stop a running tunnel.

hatch tunnel stop myapp/web

`hatch tunnel status`

List all active tunnels with their type, URL, and uptime.

hatch tunnel status

See Share a Dev Server for setup and configuration.

Sessions

`hatch session list`

List all active sessions with their domains, ports, and TTL.

hatch session list

`hatch session stop <project>/<name>`

Stop a specific session and release its ports.

hatch session stop myapp/fix-auth

`hatch session stop-all`

Stop all active sessions.

hatch session stop-all

Config

`hatch config`

Open the config file in your $EDITOR (falls back to $VISUAL, then vi).

hatch config

`hatch config validate`

Validate the config file without opening it.

hatch config validate

Other

`hatch version`

Print version, commit hash, and build date.

hatch version

`hatch completion <shell>`

Generate shell completion scripts.

hatch completion bash
hatch completion zsh
hatch completion fish

`hatch app`

Launch the GUI dashboard.

hatch app

Global flags

Flag	Description
`-v, --verbose`	Enable debug logging