CLI

The ed command line

ed is the command line for Edith. It ships inside the app, links itself onto your PATH the first time the app runs, and reaches everything the UI reaches: settings, extensions, permissions, agent usage, this Mac's metrics, playback, your clipboard, your calendar, and the machines Edith can talk to over SSH.

edh and edith are the same binary under different names. Every example in these pages works with any of the three.

The built-in manual is ed guide, which is written for agents and humans alike and is the shortest path to being useful. These pages are the complete reference: one page per command group, every flag, every default, every JSON key.

Start here

Page	What it covers
Getting started	Installing and linking the CLI, ed guide, ed schema, ed version, shell completion, and the ed <machine> ... shorthand
Conventions and contracts	The --json guarantee, stdout versus stderr, the exit code table, and which commands need the app running

This Mac

Page	What it covers
ed config	Every setting the UI exposes, and the full setting catalogue
ed app	One-shot app actions, section reveal, and PNG window snapshots
ed extensions	Turning Edith's features on and off
ed lid-awake	Closed-lid sessions, battery auto-pause and live state
ed permissions	Inspecting and requesting Edith's macOS permissions
ed usage	Agent usage: limits, cost, tokens, projects, sources, and machine attribution
ed system	CPU, memory, load, network and mounted volumes
ed music	Playback control and the local music library
ed calendar	Your agenda
ed herdr	Live Herdr sessions on this Mac and your SSH machines
ed clipboard	Clipboard history: read, copy, pin and prune
ed color	The colour picker's swatch history
ed download	The download queue and the tools that back it
ed apps	Running applications, and quitting them
ed tools	The command line tools Edith can install for you
ed shelf	The notch shelf's staged files
ed cleaner	Scanning and reclaiming disk space
ed companion	Local memory health, status, Markdown ingest and episodes

Other machines

Page	What it covers
ed machines	The machine directory: add, edit, connect, inspect, plus snippets and forwards
Running commands on a machine	The ed <machine> ... shorthand, ed machines exec, remote working directories and completion
ed machines docker	Containers, images, volumes, networks and compose projects
ed machines files	Browsing, transferring and editing files over SSH, and the undo model
ed machines power	Power state, processes and system services
ed machines thermal	Thermal readings and temporary or persistent performance profiles
ed machines workspace	Workspaces and panes

The short version

ed guide                         the built-in manual
ed config ls                     every setting and its current value
ed lid-awake on --for 30m        keep running with the lid closed for 30 minutes
ed usage limits --json           the numbers behind the rate-limit rings
ed system stats --follow         this Mac, sampled continuously
ed machines ls                   the computers Edith can reach
ed tuf docker ps                 run anything on one of them

Every reporting command that advertises --json prints exactly one document on stdout, except the two documented streaming modes. Errors, hints and notes go to stderr. Exit codes are part of the contract, so an agent can drive Edith headlessly. See conventions and contracts for the details.

These pages are mirrored to the wiki on every push to main. Edit the files here, never the wiki.