cli

Active contributors: ConradIrwin, mikayla-maki, kubkon

Purpose

crates/cli produces the small zed command-line tool that ships next to the GUI app. Its job is to find the installed Zed bundle, hand off the user's arguments to a running instance over IPC, and stream the result back. It is intentionally minimal — almost no editor logic lives here.

Directory layout

crates/cli/
├── Cargo.toml
├── README.md
├── build.rs
└── src/
    ├── cli.rs        # Library: types shared with the GUI app (CliRequest, IpcHandshake, …)
    └── main.rs       # The `zed` binary

Key abstractions

Type	File	Description
CliRequest	crates/cli/src/cli.rs	Args + flags forwarded from CLI to GUI
CliResponse	crates/cli/src/cli.rs	Status / stream events sent back to CLI
IpcHandshake	crates/cli/src/cli.rs	One-shot handshake bound to a temp socket
IpcOneShotServer	re-export	OS-level IPC server (Unix socket / Windows named pipe)
URL_PREFIX	crates/cli/src/main.rs	["zed://", "http://", "https://", "file://", "ssh://"]
FORCE_CLI_MODE_ENV_VAR_NAME	crates/cli/src/cli.rs	Env var that forces CLI behaviour even in GUI context

How it works

sequenceDiagram
    participant U as User
    participant C as zed (CLI)
    participant Z as Zed (GUI)

    U->>C: zed src/foo.rs
    C->>C: Find Zed bundle (per-OS)
    C->>C: Spawn Zed if not running
    C->>Z: IpcOneShotServer handshake
    Z->>C: stream of CliResponse
    C-->>U: print stdout / open file

• On macOS the bundle is found via the standard launch services lookup.
• On Linux it is found via $ZED_PATH, which zed, or the sibling binary location.
• On Windows the path comes from the install registry key.

URLs prefixed with zed://, ssh://, or any other entry in URL_PREFIX are forwarded straight through to the GUI process and routed to the appropriate handler (crates/zed/src/zed/open_url_modal.rs).

Integration points

• Talks to: the running zed desktop app via Unix sockets / Windows named pipes, using types from this crate.
• Used by: users at the shell, script/zed-local, and editor integrations (e.g. git opening Zed as $EDITOR).
• Other CLIs: crates/install_cli adds a cli: install action inside the GUI that copies the zed shim to /usr/local/bin.

Entry points for modification

• Adding a new flag — extend CliRequest, then handle it in crates/zed/src/zed/open_listener.rs.
• Adding a new URL scheme — append to URL_PREFIX and register a handler on the GUI side.
• Cross-platform launcher behaviour — crates/cli/src/main.rs has per-OS sections marked with cfg.

Related pages

• zed — the GUI app receiving CLI requests
• Remote development — how ssh:// URLs become remote sessions