zed

fork of gpui

Fork

zed docs src reference cli.md

5.8 kB · 266 lines

Markdown

at master

Mohammad Adnaan · docs: Document the `--existing` CLI option (#61979) · 3mo ago

9c7a5c94

title: CLI Reference description: "Reference for Zed's command-line interface (CLI), including opening files and directories, integrating with tools, and controlling Zed from scripts." #

CLI Reference #

Use Zed's command-line interface (CLI) to open files and directories, integrate with other tools, and control Zed from scripts.

Installation #

macOS: Run the {#action cli::InstallCliBinary} command from the command palette ({#kb command_palette::Toggle}) to install the zed CLI to /usr/local/bin/zed.

Linux: The CLI is included with Zed packages. The binary name may vary by distribution (commonly zed or zeditor).

Windows: The CLI is included with Zed. Add Zed's installation directory to your PATH, or use the full path to zed.exe.

Usage #

zed [OPTIONS] [PATHS]...

Opening Files and Directories #

Open a file:

zed myfile.txt

Open a directory as a workspace:

zed ~/projects/myproject

Open multiple files or directories:

zed file1.txt file2.txt ~/projects/myproject

Open a file at a specific line and column:

zed myfile.txt:42        # Open at line 42
zed myfile.txt:42:10     # Open at line 42, column 10

Options #

`-w`, `--wait` #

Wait for all opened files to be closed before the CLI exits. When opening a directory, waits until the window is closed.

This is useful for integrating Zed with tools that expect an editor to block until editing is complete (e.g., git commit):

export EDITOR="zed --wait"
git commit  # Opens Zed and waits for you to close the commit message file

`-n`, `--new` #

Open paths in a new workspace window, even if the paths are already open in an existing window:

zed -n ~/projects/myproject

`-a`, `--add` #

Add paths to the currently focused workspace instead of opening a new window. When multiple workspace windows are open, files open in the focused window:

zed -a newfile.txt

`-r`, `--reuse` #

Reuse an existing window, replacing its current workspace with the new paths:

zed -r ~/projects/different-project

`-e`, `--existing` #

Open paths in an existing Zed window instead of creating a new one:

zed -e myfile.txt

By default (without -n, -a, -r, or -e), directories open in the current window's sidebar. You can change this default with the cli_default_open_behavior setting. See Windows & Projects for more details.

`--diff <OLD_PATH> <NEW_PATH>` #

Open a diff view comparing two files. Can be specified multiple times:

zed --diff file1.txt file2.txt
zed --diff old.rs new.rs --diff old2.rs new2.rs

`--foreground` #

Run Zed in the foreground, keeping the terminal attached. Useful for debugging:

zed --foreground

`--user-data-dir <DIR>` #

Use a custom directory for all user data (database, extensions, logs) instead of the default location:

zed --user-data-dir ~/.zed-custom

Default locations:

macOS: ~/Library/Application Support/Zed
Linux: $XDG_DATA_HOME/zed (typically ~/.local/share/zed)
Windows: %LOCALAPPDATA%\Zed

`-v`, `--version` #

Print Zed's version and exit:

zed --version

`--completions <SHELL>` #

Generate shell completions for the zed CLI:

Bash #

Add to ~/.bashrc:

eval "$(zed --completions bash)"

Elvish #

Add to ~/.config/elvish/rc.elv:

set edit:completion:arg-completer[zed] = { |@args|
    eval (zed --completions elvish | slurp)
    $edit:completion:arg-completer[zed] $@args
}

Fish #

Add to ~/.config/fish/config.fish:

zed --completions fish | source

Nushell #

Add to ~/.config/nushell/config.nu:

mkdir ($nu.data-dir | path join "vendor/autoload")
^zed --completions nushell | save --force ($nu.data-dir | path join "vendor/autoload/zed.nu")

Powershell #

Add to $PROFILE:

(&zed --completions powershell) | Out-String | Invoke-Expression

Zsh #

Add to ~/.zshrc:

eval "$(zed --completions zsh)"

`--uninstall` #

Uninstall Zed and remove all related files (macOS and Linux only):

zed --uninstall

`--zed <PATH>` #

Specify a custom path to the Zed application or binary:

zed --zed /path/to/Zed.app myfile.txt

Reading from Standard Input #

Read content from stdin by passing - as the path:

echo "Hello, World!" | zed -
cat myfile.txt | zed -
ps aux | zed -

This creates a temporary file with the stdin content and opens it in Zed.

URL Handling #

The CLI can open zed://, file://, and ssh:// URLs:

zed zed://settings
zed file:///Users/whatever/.zshrc
zed ssh://me@example.com/abs/path
zed ssh://me@example.com:/abs/path
zed ssh://me@example.com/~/project
zed ssh://me@example.com:~/project

Using Zed as Your Default Editor #

Set Zed as your default editor for Git and other tools:

export EDITOR="zed --wait"
export VISUAL="zed --wait"

Add these lines to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc).

macOS: Switching Release Channels #

On macOS, you can launch a specific release channel by passing the channel name as the first argument:

zed --stable myfile.txt
zed --preview myfile.txt
zed --nightly myfile.txt

WSL Integration (Windows) #

On Windows, the CLI supports opening paths from WSL distributions. This is handled automatically when launching Zed from within WSL.

Exit Codes #

Code	Meaning
`0`	Success
`1`	Error (details printed to stderr)

When using --wait, the exit code reflects whether the files were saved before closing.