1# CLI Reference
2
3Zed includes a command-line interface (CLI) for opening files and directories, integrating with other tools, and controlling Zed from scripts.
4
5## Installation
6
7**macOS:** Run the `cli: install` command from the command palette ({#kb command_palette::Toggle}) to install the `zed` CLI to `/usr/local/bin/zed`.
8
9**Linux:** The CLI is included with Zed packages. The binary name may vary by distribution (commonly `zed` or `zeditor`).
10
11**Windows:** The CLI is included with Zed. Add Zed's installation directory to your PATH, or use the full path to `zed.exe`.
12
13## Usage
14
15```sh
16zed [OPTIONS] [PATHS]...
17```
18
19## Opening Files and Directories
20
21Open a file:
22
23```sh
24zed myfile.txt
25```
26
27Open a directory as a workspace:
28
29```sh
30zed ~/projects/myproject
31```
32
33Open multiple files or directories:
34
35```sh
36zed file1.txt file2.txt ~/projects/myproject
37```
38
39Open a file at a specific line and column:
40
41```sh
42zed myfile.txt:42 # Open at line 42
43zed myfile.txt:42:10 # Open at line 42, column 10
44```
45
46## Options
47
48### `-w`, `--wait`
49
50Wait for all opened files to be closed before the CLI exits. When opening a directory, waits until the window is closed.
51
52This is useful for integrating Zed with tools that expect an editor to block until editing is complete (e.g., `git commit`):
53
54```sh
55export EDITOR="zed --wait"
56git commit # Opens Zed and waits for you to close the commit message file
57```
58
59### `-n`, `--new`
60
61Open paths in a new workspace window, even if the paths are already open in an existing window:
62
63```sh
64zed -n ~/projects/myproject
65```
66
67### `-a`, `--add`
68
69Add paths to the currently focused workspace instead of opening a new window:
70
71```sh
72zed -a newfile.txt
73```
74
75### `-r`, `--reuse`
76
77Reuse an existing window, replacing its current workspace with the new paths:
78
79```sh
80zed -r ~/projects/different-project
81```
82
83### `--diff <OLD_PATH> <NEW_PATH>`
84
85Open a diff view comparing two files. Can be specified multiple times:
86
87```sh
88zed --diff file1.txt file2.txt
89zed --diff old.rs new.rs --diff old2.rs new2.rs
90```
91
92### `--foreground`
93
94Run Zed in the foreground, keeping the terminal attached. Useful for debugging:
95
96```sh
97zed --foreground
98```
99
100### `--user-data-dir <DIR>`
101
102Use a custom directory for all user data (database, extensions, logs) instead of the default location:
103
104```sh
105zed --user-data-dir ~/.zed-custom
106```
107
108Default locations:
109
110- **macOS:** `~/Library/Application Support/Zed`
111- **Linux:** `$XDG_DATA_HOME/zed` (typically `~/.local/share/zed`)
112- **Windows:** `%LOCALAPPDATA%\Zed`
113
114### `-v`, `--version`
115
116Print Zed's version and exit:
117
118```sh
119zed --version
120```
121
122### `--uninstall`
123
124Uninstall Zed and remove all related files (macOS and Linux only):
125
126```sh
127zed --uninstall
128```
129
130### `--zed <PATH>`
131
132Specify a custom path to the Zed application or binary:
133
134```sh
135zed --zed /path/to/Zed.app myfile.txt
136```
137
138## Reading from Standard Input
139
140Read content from stdin by passing `-` as the path:
141
142```sh
143echo "Hello, World!" | zed -
144cat myfile.txt | zed -
145ps aux | zed -
146```
147
148This creates a temporary file with the stdin content and opens it in Zed.
149
150## URL Handling
151
152The CLI can open `zed://`, `http://`, and `https://` URLs:
153
154```sh
155zed zed://settings
156zed https://github.com/zed-industries/zed
157```
158
159## Using Zed as Your Default Editor
160
161Set Zed as your default editor for Git and other tools:
162
163```sh
164export EDITOR="zed --wait"
165export VISUAL="zed --wait"
166```
167
168Add these lines to your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`).
169
170## macOS: Switching Release Channels
171
172On macOS, you can launch a specific release channel by passing the channel name as the first argument:
173
174```sh
175zed --stable myfile.txt
176zed --preview myfile.txt
177zed --nightly myfile.txt
178```
179
180## WSL Integration (Windows)
181
182On Windows, the CLI supports opening paths from WSL distributions. This is handled automatically when launching Zed from within WSL.
183
184## Exit Codes
185
186| Code | Meaning |
187|------|---------|
188| `0` | Success |
189| `1` | Error (details printed to stderr) |
190
191When using `--wait`, the exit code reflects whether the files were saved before closing.