The whole app, scriptable from your terminal
The portbay CLI is a thin layer over the same Rust core as the app: the same registry, the same supervisor, the same board. If the UI can do it, your shell probably can too.
How do I manage local dev sites from the terminal?
A dev-environment CLI is only worth using if it reads and writes the same state as the app's UI. A parallel hand-rolled setup — php -S localhost:8000 on a port the app knows nothing about, no domain, no certificate — drifts from what the tool believes within a day. PortBay's CLI installs alongside the app (brew install --cask portbay) and talks to the same Rust core and registry, so nothing diverges. portbay list, status, start, stop --all, restart, logs --limit and open cover the everyday loop; portbay doctor diagnoses runtimes, ports, registry and certificate state; portbay export plus a portbay.yml config-as-code file make a project reproducible with portbay add. The board, sandbox, databases, certificates, DNS and import each have subcommands, and every command takes --json, which makes the CLI a scripting surface for agents. It expects the PortBay daemon to be running.
Verified against the product, 2026-07-10.
Add, start, open: the terminal loop
The same registry the app uses, driven from a shell: add a folder, start it, and the .test URL is live.
The commands that carry the day
- Install once, get both
- Run the everyday loop
- Diagnose with doctor
- Commit the setup
- Script it, or let agents
Install once, get both
The Homebrew cask installs PortBay.app and the bundled portbay CLI together. Uninstalling through Homebrew removes them together too.
brew tap portbay-app/portbay && brew install --cask portbayRun the everyday loop
List projects with live status, start and stop them, tail logs, open the project's URL in the browser. The daemon (the app) does the work; the CLI is the remote.
portbay start blog && portbay open blogDiagnose with doctor
One command checks the runtime, ports, registry and certificate state and says what is wrong, before you start reading logs.
portbay doctorCommit the setup
portbay export writes .portbay.json, and portbay.yml captures hostname, runtime, HTTPS, env and linked databases as config-as-code. A teammate runs portbay add and gets an identical setup.
Script it, or let agents
Every command takes --json. Shell completions generate for your shell, and the board's own subcommands mean a script or an agent can file and move cards without the UI.
portbay --json statusThe CLI, tier by tier
The CLI expects the PortBay daemon to be running; in the current build that means the app is open.
Scripting a GUI-only dev tool
When the tool has no CLI, automation means AppleScript, screenshots in CI, or keeping a parallel shell setup that drifts from what the app believes.
One core, two faces: the CLI reads and writes the same registry as the app, so scripts and clicks never disagree.
# The GUI-only workflow, automated badly$ osascript -e 'tell application "SomeDevApp" to activate' # then what? # Or a parallel hand-rolled setup the app knows nothing about$ php -S localhost:8000 & # different port than the app used$ open http://localhost:8000 # http, no domain, no cert # Or "just remember" to click start on the right five projects
One app, not a stack of tools
Agent task board
A Kanban board both you and your agents work. Cards are Markdown in the repo; moving one to To Do dispatches the agent.
Explore →SSH workspace
Save a host once: real terminal, SFTP browser with inline ⌘S editing, click-to-start tunnels, and host panels, on system OpenSSH.
Explore →Local databases
Six engines, one wizard: isolated data dirs, dedicated ports, supervision, and connection vars injected into linked projects on start.
Explore →Asked before downloading
How do I install the CLI?
PortBay's CLI ships with the app: brew tap portbay-app/portbay, then brew install --cask portbay installs PortBay.app and the bundled portbay command together. The DMG install includes it too.
Does the CLI work without the app open?
The CLI needs the PortBay daemon, which in the current build means the app should be open (the menu-bar mode counts). The CLI then reads the registry and drives the same Process Compose supervisor the app uses.
Can I script PortBay from the terminal?
Yes. Every command accepts --json for machine-readable output, completions generate for your shell, and --registry points at an isolated registry file for testing. The board subcommands make it a scripting surface for agents as well as humans.
What is portbay doctor?
A diagnostic pass over the runtime, ports, registry and certificate state that names what is wrong instead of leaving you to correlate logs. It is the first command to run when a project will not start.
What is portbay-agent?
The bundled agent engine. It powers local-model dispatch from the task board (an Ollama card launches it in a terminal with the model selected on the card) and agent-specific flags and subcommands proxy through to it from the portbay CLI.
Give your projects and your agents a real local home.
Download for macOSFree & open source · macOS 11+ on Apple Silicon · Pro from $10/mo