Docs › Get started › Introduction

Getting started

Gretl gives every local service a name. Once registered, you can start, stop, resolve, and open by name — from the CLI, from your code, or from your browser toolbar.

Installation

Install the desktop app, the CLI, or both. They talk to the same daemon — pick whichever surface fits the moment.

# macOS (Homebrew)
brew install slowdutch/tap/gr

# macOS (.dmg) · Windows (.exe) · Linux (.AppImage)
# https://gretl.dev/download

# Linux one-liner
curl -fsSL https://gretl.dev/install.sh | sh

Verify the daemon is up:

gr doctor
# ✓ daemon running on 127.0.0.1:11611
# ✓ gr.toml found at ~/dev/jobs/gr.toml
# ✓ 0 conflicts, 0 orphan PIDs

Local-first. The daemon binds to 127.0.0.1 only. No telemetry without opt-in. gr never makes outbound network calls except on gr update.

Your first service

gr add jobs-server --port 7401 --cmd "npm run dev:server"
gr start jobs-server
gr open jobs-server   # launches http://localhost:7401

From here, never type :7401 again. The port is an implementation detail.

gr.toml

Most teams check a gr.toml into the repo. It declares services and groups in plain TOML:

# gr.toml
[service.jobs-server]
port = 7401
cmd  = "npm run dev:server"
group = "@jobs"
ready = "http://localhost:7401/health"

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

[group."@jobs"]
description = "Everything for the Jobs feature"

Groups

Groups boot a stack at once, in dependency order, with health checks:

gr group start @jobs
# → jobs-server (waiting on /health) ✓ 1.1s
# → jobs-board  ✓ 0.3s
# ready in 1.4s

Docs › CLI › Reference

CLI reference

The gr binary is the primary surface. Everything in the desktop app and Chrome extension goes through the same commands underneath.

Lifecycle

Command	Description
gr start <name>	Start a registered service. Returns when the ready-check passes.
gr stop <name>	Send SIGTERM, then SIGKILL after `--grace` (default 5s).
gr restart <name>	Stop + start with the same args.
gr group start @<g>	Start every service in a group, in `depends_on` order.
gr group stop @<g>	Reverse-order stop.
gr kill :<port>	Free a port by number (escape hatch).

Inspection

Command	Description
gr status	Tabular view of every known service.
gr logs <name> -f	Tail logs. Falls through to the underlying process stdout/stderr.
gr env <name>	Print resolved env (`PORT`, `GRETL_*`, etc).
gr resolve <name>	Print the URL — useful in scripts: `open $(gr resolve admin)`.

Discovery

Find unmanaged listeners on your machine and let Gretl take ownership:

gr detect
# PORT   PID    PROC          SUGGEST
# 5173   38901  node          adopt as 'vite'?
# 3000   38933  next-server   adopt as 'next'?

gr adopt 5173 --as vite

Diagnostics

gr doctor walks every known service and reports:

Port collisions (two services claiming the same port)
PID drift (the daemon's recorded PID no longer matches the listener)
Orphaned children (the parent died, the port is still held)
Stale unix sockets in ~/.gr/sock

Pass --fix to auto-resolve anything safe.