zaps-usage

name

zaps-usage

description

Use when running or inspecting local dev services through the ZAPS CLI — starting/stopping/restarting services, attaching the TUI (`zaps up`/`attach`), running tasks, streaming logs, checking which services are running and on what ports, reloading config, or managing the daemon. Trigger whenever the user wants to bring up, tear down, restart, or check the status of their local dev environment with zaps — including single-command asks like "restart the api", "what ports are my services on", "list running services", or "tail the web logs" — so the exact zaps command, flags, and session targeting are correct. Not for authoring config files — use the zaps-config skill for that.

ZAPS Usage Skill

Trigger

Activate when user asks to start/stop/manage local development sessions, run tasks, view logs, or interact with running services (not config authoring).

First Action

When this skill loads, immediately run zaps prime-agent to get the current project overview (services with runtime state/ports + tasks). This primes your context before executing the user's request.

Output

Query/service commands print a human table by default. For machine-readable output pass --json (pretty JSON) or --toon (TOON), or set ZAPS_FORMAT=json|toon to make it the default for every command. Coding agents are auto-detected (CLAUDECODE / CURSOR_TRACE_DIR) and default to TOON with no flag.

Usage

Services

zaps ps           # list services with state/ports/url (--json)
zaps start [svc]  # start service(s), all if omitted
zaps stop [svc]   # stop service(s)
zaps restart [svc]# restart service(s)

Tasks & Logs

zaps run <task>   # run a task (--json)
zaps tasks        # list tasks (--json)
zaps logs [svc]   # dump logs, -f to stream, --tail <n>

Query

zaps ls           # list active sessions (--json)
zaps inspect <svc># service details (--json)
zaps config       # validate+print config (--json, --path)
zaps events       # stream daemon events (--filter <type>)

Session & Daemon

zaps up             # attach if running, else create + start + attach TUI
zaps up -d          # create + start services detached (no TUI); attach later with `zaps attach`
zaps attach         # attach the TUI to a running session (use `-s <id|name>` to pick one)
zaps reload         # reload config for the running session (CLI form of the dashboard `c`)
zaps down           # stop all services and destroy the session
zaps daemon start   # start the background daemon (usually implicit via `zaps up`)
zaps daemon status  # daemon PID + session list (--json / --toon)
zaps daemon ping    # check the daemon is responsive
zaps daemon stop    # full cleanup: stops every service in every session, then shuts the daemon down
                    #   prints `Stopped <n> session(s), <m> service(s).`

Target a specific session with the global -s, --session <id|name> flag (before the command): zaps -s my-app down, zaps -s my-app restart api. Without it, ZAPS resolves the session for the current directory.

TUI

zaps up attaches the interactive dashboard. Key interactions:

Global
  Ctrl-K / :  command palette (fuzzy actions)
  ?           help overlay
  t           task picker
  f           open the latest failure's captured output
  x           acknowledge (clear sticky failure toasts)
  q / Ctrl-C  detach (services keep running)
  Ctrl-D      shut down the session
  Esc         close overlay / leave view

Dashboard
  ↑↓ / j k    navigate services
  r / s       restart / start-stop selected
  a / c       restart all / reload config
  l / o       logs / open URL
  R           docker rebuild     z / Z  zoom service / TUI pane
  E           edit-capture pane  d      shut down session

Task picker (t)
  type        fuzzy filter
  Enter       run in the default mode (ui.task.defaultMode, default background)
  Tab         run live in a tmux pane
  Esc         close

Log view (l)
  ↑↓ / j k    scroll (scroll to bottom resumes live follow)
  Esc         back

Run modes: a task launched with Enter runs in the configured default mode (background unless ui.task.defaultMode: pane); Tab always runs it live in a tmux pane that stays open on completion. Background runs notify via a toast — transient on success, sticky on failure (ack with x); failures also fire an out-of-band terminal notification per ui.notifications. Press f for the failed-output overlay, then p to escalate to a tmux popup.

Other

zaps --help # see all functions

Behavior Notes

• Detached services (detached: true) and detached sessions (zaps up -d) run pane-less — there is no terminal to scroll. Read their output with zaps logs <svc> (-f to stream). Lifecycle (start/stop/restart) works normally.
• Lazy panes (non-autostart services). A service with flags.start: false (or explicit lazyPane: true) now boots pane-less — its tmux pane only appears when you zaps start <svc> (or restart from stopped), at its declared layout position; a zaps stop <svc> drops the pane and re-expands survivors. Crash + restart keep the pane. zaps logs <svc> returns [] before the first start, streams live while the service is running, and returns the retained history after stop. To reserve an empty pane at boot instead, set lazyPane: false on the service.
• Config reload is validate-then-swap: an invalid edit is reported and the running session keeps the old config (it is never torn down). In the TUI, a changed config shows a config changed — press c to reload header hint; press c (when idle) to apply.
• --tail <n> on zaps logs must be a positive integer; otherwise the command errors with Invalid --tail value "<x>": expected a positive integer.
• zaps events validates the resolved session before subscribing — if no matching session exists it errors immediately instead of hanging.
• Error messages you may surface to the user:
  • Port 5432 already in use (pid 1234 postgres) — a service's expected port is taken (pre-flight, before start). Free the port or stop the owning process.
  • Dependency "db" not ready — shown as a service's error when a dependsOn target never became ready; fix or start the dependency first.
• Removed env vars: ZAPS_PANE_MAP and ZAPS_IPC_SOCKET no longer exist (they never worked) — ignore any references to them.

AI

zaps prime-agent  # TOON overview of services (runtime state/ports) + tasks

Core Workflow

Restart dev after package install:

pnpm install @example/pkg
zaps restart dev

Get details for testing:

zaps ps
agent-browser open http://localhost:3000 # Open dev
agent-browser open http://localhost:8025 # Open Mailpit for E-Mail

Run prisma migration:

zaps run prisma:migrate

Now run zaps prime-agent to prime your context.