Commands

Zapper commands operate on the current project by default. Use --config to point at a specific config file, --profile <name> for a one-off profile override, and --instance <name> to target a named instance.

The reference below is generated from the commander command tree, so it always matches zap <command> --help. See Tasks for task configuration, Configuration for zap.yaml fields, and Command Output for the JSON/result contract.

Global Options

zap up [services...]

Aliases: start, s, u

Start all processes or specific processes

zap down [services...]

Aliases: stop, delete

Stop all processes or specific processes

zap kill [project]

Kill all native processes and Docker containers across all instances for a project

zap restart [services...]

Aliases: r

Restart all processes or specific processes

zap watch [services...]

Aliases: w

Watch Docker service paths and restart or rebuild on changes

zap status [services...]

Aliases: ps

Show status (native processes + Docker), optionally for specific services

zap ls [services...]

List configured services with details and assigned ports

zap logs <services...>

Aliases: l

Show logs for one or more services

zap startup-log <services...>

Show saved startup output for one or more services

zap reset

Stop all processes and delete the .zap directory

zap init

Initialize local zap state (instance + ports + volumes)

zap instance

Manage the selected local instance

zap instance label [label...]

Show or set the label for the selected instance

zap volume

Manage Zapper-generated Docker volumes (list, prune, reset)

zap volume list <service>

List Docker volumes for a service

zap volume prune

Remove stale managed Docker volumes after confirmation

zap volume reset

Reset managed Docker volume state for the instance

zap clone [services...]

Clone all repos defined in native services (respects git_method)

zap task [task]

Aliases: t, run

Run a one-off task by name, or list all tasks if no task specified

zap profile

Aliases: p

Select a profile interactively and apply its services.

Use ↑/↓ to move and Enter to switch. The active profile is marked and initially selected. The picker closes before service progress begins; success exits the command. Escape or Ctrl+C cancels without changes. Without a terminal, use get or set. Bare --json still reports the current profile.

zap profile list

List configured profiles

zap profile get

Alias: current

Print the current profile

zap profile set <name>

Alias: use

Stop excluded services, start required services, and save the profile

zap profile reset

Apply the default profile, stopping excluded services and starting required services

zap state

Show the current state JSON

zap stack

Inspect the selected stack id and known profile stacks

zap stack id

Print the current stack id

zap stack current

Show the current stack

zap stack list

List known profile stacks

zap git

Git operations across all native repos

zap git status

Aliases: gst

List branch and dirty/clean for all native repos

zap git pull

Aliases: ggpur

Pull latest for all native repos

zap git checkout <branch>

Aliases: gco

Checkout a branch across all native repos

zap git stash

Aliases: gsta

Stash any dirty changes across all native repos

zap config

Show the processed config object as minified JSON

zap validate

Validate zap.yaml without initializing local state

zap env [service]

Show resolved environment variables for a service

zap launch [name]

Open homepage by default, or open a configured link by name

zap open [name]

Aliases: o

Choose a configured project link interactively

zap home

Print the configured homepage URL

zap links

List configured links, including the homepage

zap notes

Print configured project notes

zap global

Aliases: g

Global operations across projects (info, list, prune, kill)

zap global list [project]

Aliases: ls, l

List all global Zapper resources, or a single project

zap global info [project]

Show global resources for a project

zap global prune

Prune stale registry entries and orphaned resources

zap global kill [project]

Kill all native process + Docker resources for a project

zap system

Machine-wide Zapper project registry and orphaned resource audit

zap system projects

List registered Zapper projects and validate their roots

zap system registry

Manage the machine-wide project registry

zap system registry prune

Remove stale entries from the project registry

zap system registry forget <target>

Forget a registry entry by id, project root, or config path

zap system registry repair

Prune stale entries and re-validate all projects

zap system resources

Audit and clean up orphaned system resources

zap system resources audit

Audit orphaned native processes and Docker containers

zap system resources cleanup

Delete orphaned system resources after confirmation

Shortcuts

Convenience top-level shortcuts that delegate to a subcommand.

JSON Output

Most non-streaming commands support --json. Action commands also support JSON Lines streaming with --jsonl where implemented. When --json is enabled, Zapper suppresses incidental human logs and warnings so stdout stays parseable. Streaming commands (logs, startup-log, task) keep their stream output and are not JSON-encoded.

For the command result and rendering contract, see Command Output.

System Registry Storage

System commands inspect machine-wide Zapper state rather than only the current repository. They back desktop integrations, project discovery, and orphaned resource cleanup.

On macOS, the system registry defaults to ~/Library/Application Support/Zapper/registry.json. On Linux, it defaults to $XDG_STATE_HOME/zapper/registry.json, or ~/.local/state/zapper/registry.json when XDG_STATE_HOME is unset. Set ZAPPER_SYSTEM_STATE_HOME to override the directory, or ZAPPER_DISABLE_SYSTEM_REGISTRY=1 to disable registry writes.