Usage

Directories

Open the current directory:

zero .

Or another directory:

zero path/to/markdown

With the desktop app installed, zero [path] opens the directory in it and exits. Without it, or with --host or --port, it serves in a browser, as zero browser [path] does. On a machine without a UI (an SSH session, or Linux without a display) it tells you to run zero [path] --remote, which prints a zero connect command to run on your computer (Remote hosts).

zero browser [path] always serves in a browser and takes the same flags. Subcommand names take precedence over directories, so open a directory named browser, walkthrough, or daemon as zero ./browser, zero ./walkthrough, or zero ./daemon.

Serve several directories with a repeatable --path (a positional path is shorthand for one); overlapping directories fail before starting:

zero --path ~/work --path ~/personal

Projects and worktrees

Zero looks for git repositories (including linked worktrees) up to --scan-depth folders deep in each directory (default 10; 0 checks only the served directories) and lists them in the project picker (Cmd/Ctrl+O). It stops descending at a repository and skips hidden, node_modules, and vendor folders. Only one project is read at a time, and every switch reads it from disk. Each switch restores that project's tabs and expanded folders, including after reloads. --depth limits the file tree within a project.

A repository opens whole: its own folders cannot be opened as projects, and Open folder only browses folders outside repositories. A repository with worktrees is one picker entry that opens the last-used worktree; press → (or click its arrow) to choose a worktree by branch. Worktrees of a served repository open wherever they live, even outside the served directories. Repositories are named after their origin remote, else their folder. The explorer header shows the repository and branch; when the repository has worktrees, click the branch to switch. Linked worktrees get a colored fork icon.

Welcome

A project that opens with no tabs to restore shows the Welcome tab: shortcuts to open a project, find a file, and run a command; the project's branch, uncommitted changes, and walkthroughs; every served project (when there is more than one) with a filter and each repository's worktrees; and a short guide in which every entry runs what it describes. Click Zero in the status bar, or run Help › Welcome from the command palette, to open it again. Turn it off with Workbench › Show Welcome on Startup in Settings; the project picker then opens on the first launch instead.

With no tab open, the document area names what the current sidebar view offers: a file to choose, a search to run, changes to review, or a walkthrough to start.

Host and port

Without --port, Zero uses the first free port from 7971 through 7980. Use --host to bind a specific IP address or --port to select an exact port.

Setting either one always serves in a browser. For parallel agent sessions or worktrees, use a different port for each server, or let the OS select an available port:

zero . --port 8123 --no-open
zero . --port 0 --no-open

Use the URL printed at startup. Each server serves its own roots and stops independently. An occupied explicit port fails without stopping another server. Open Zero by localhost or an IP address; other hostnames are refused, so websites cannot reach it through DNS rebinding. If the range is full, Zero can stop all verified instances after confirmation.

Files

Every file within --depth is served, whatever its type. .git, node_modules, and vendor folders are always skipped, and .git files are always hidden.

The explorer's filename filter accepts comma-separated glob patterns in Go path.Match syntax (*, ?, [...]), matched case-insensitively against each file's base name. It only changes tree visibility, preserving open documents. Global content search covers every served text file regardless of the tree filter. Markdown image dependencies remain available within the served root. Source Control lists and diffs every change and commit in the repository checkout, regardless of --depth and skipped folders.

Daemon

zero daemon is plumbing for the desktop app: one long-lived Zero per user, reachable only through a private Unix socket (macOS and Linux), whose directories are added while it runs and remembered across restarts. Clients start it on demand; it stops after 30 minutes without requests. To check on it or stop it:

zero daemon status
zero daemon stop

zero daemon ensure starts it unless it is running; --json prints status as JSON.

All options

zero --help
zero daemon run --help

zero daemon subcommands take --socket to use another socket path; run and ensure also take --depth, --scan-depth, and --idle-exit (0 never stops).