Docs › Reference

Reference

Configuration files, environment variables, on-disk paths, and a triage table for the things that go wrong on real machines.

gr.toml reference

One gr.toml per repo (or per machine in ~/gr.toml). Everything is optional except name and port on a service.

Top-level keys

Key	Type	Default	Notes
project	string	repo dirname	Display name in the desktop app's window title.
root	string	"."	Base for relative `cwd` values.
env_file	string	".env"	Loaded into every service's env (KEY=VAL syntax).

[service.<name>]

Key	Type	Required	Notes
port	int	yes	Listening port.
cmd	string	no	Shell command. Run via the user's `$SHELL` with `-c`.
cwd	string	no	Defaults to `root`.
env	table	no	Per-service env. Wins over `env_file`.
group	string	no	Group name (must start with `@`).
ready	string	no	HTTP URL — PA polls until it returns 2xx.
depends_on	string[]	no	Names that must be running first.
restart	"never" \| "on-failure" \| "always"	no	Default `"on-failure"`.
log_file	string	no	Override the default log path (see File paths).

[group."@<name>"]

Key	Type	Notes
description	string	Shown in the desktop app and `gr group ls`.
parallel	bool	Default `true`. Set `false` to start strictly in `depends_on` order.

Full example

# gr.toml
project = "jobs"
env_file = ".env.local"

[service.jobs-server]
port = 7401
cmd  = "npm run dev:server"
group = "@jobs"
ready = "http://localhost:7401/health"
restart = "on-failure"

[service.jobs-board]
port = 7400
cmd  = "npm run dev:web"
group = "@jobs"
depends_on = ["jobs-server"]

[service.postgres]
port = 5432
cmd  = "docker compose up postgres"
group = "@data"

[group."@jobs"]
description = "Jobs feature — board + API + worker"

[group."@data"]
description = "Postgres + Redis + mailpit"

Environment variables

Every service started by Gretl gets these variables in addition to its own env:

Variable	Value
PORT	The service's `port`. Most frameworks pick this up automatically.
GRETL_NAME	The service name.
GRETL_GROUP	The group name, or empty.
GRETL_DAEMON_URL	The daemon's URL — services can use this to `resolve` peers.
GRETL_PROJECT	From `gr.toml`'s `project` key.
GRETL_LOG_DIR	Where this service's logs are written.

Inside your code, prefer gr.url("postgres") over reading GRETL_DAEMON_URL directly — the SDK handles caching, reconnects, and ready-checks for you.

File paths

Path	Purpose
~/.gr/config.toml	Daemon settings: bind address, auth token, log retention, telemetry opt-in.
~/.gr/gr.toml	Global service catalog. Repo-level `gr.toml` wins for the same name.
~/.gr/state.db	SQLite — running PIDs, last-known status, event log.
~/.gr/logs/<service>/YYYY-MM-DD.log	Per-service log file. Rotated daily, compressed after 7 days.
~/.gr/sock	Unix socket for the local daemon (macOS/Linux). On Windows: named pipe `\\.\pipe\gr`.
~/.gr/extension.json	Settings shared with the browser extension.

Troubleshooting

Run gr doctor first — it auto-detects most of these and offers a fix. The table below is for when you want to know what it's actually doing.

port_in_use A non-PA process holds your port. Run gr adopt <port> --as <name> to take ownership, or gr kill :<port> to free it.

ready_timeout Process started but the ready-check URL never returned 2xx within 30s. Increase with --timeout, or fix the health endpoint. gr logs <name> tells you why.

pid_drift PA's recorded PID isn't the listener anymore — usually a crash followed by a manual restart. gr doctor --fix rebinds.

orphaned children Parent process died, the port is still held. gr doctor --fix kills the holder; --keep instead adopts it.

daemon_offline The CLI/extension can't reach the daemon. Run gr daemon start, or open the desktop app. On macOS, the launchd agent lives at ~/Library/LaunchAgents/dev.gretl.gr.plist.

stale unix socket Daemon was killed without a clean shutdown. Delete ~/.gr/sock and start the daemon again.

conflicting gr.toml Two checked-out repos define the same service name. Either rename one, or scope it: name = "jobs/server" is legal.

extension can't connect Loopback fetches from extensions require http://127.0.0.1 (not localhost). The default config already uses 127.0.0.1; check chrome://extensions > Gretl > site access.

slow start on macOS Gatekeeper scans the binary on first launch. Add gr to System Settings > Privacy & Security > Developer Tools for your terminal, or run xattr -d com.apple.quarantine $(which pa).

Still stuck? Run gr support bundle. It writes a redacted zip with config, recent logs, and gr doctor output to ~/Desktop — attach it to your bug report.