Gemini CLI, pointed at a card instead of a prompt
PortBay launches the gemini binary you already installed with the card's brief as its prompt, inside a project that is running at a real URL. Gemini is also one of four agents PortBay can wire to the board over MCP.
How do I run Gemini CLI on a queue of tasks?
Gemini CLI takes a prompt and works it, which makes the first run easy and the tenth run hard to account for. PortBay turns each run into a card. Write the card, assign Gemini, and move it to To Do: PortBay spawns `gemini -p "<the card>"` with the working directory set to the project, headless, no terminal tab to keep. That project is not a bare checkout — it is already serving on its own .test domain with a trusted certificate, with a per-project database attached and outgoing mail captured, so the agent can load the page it just changed and read the log it just wrote. Gemini is one of four agents PortBay can also connect the other way: Settings → Integrations writes a project-scoped .gemini/settings.json so a running session can read the board, claim a card and move it itself. A strike system stops a card that fails three times.
A card dispatched as gemini -p
The card's brief becomes the prompt argument. Progress, the comment and the move to Done all land back on the card.
Your first Gemini card
Six steps from a clean Mac to a Gemini run you can review at a real URL. Every command runs as written.
- Install PortBay
- Add your project
- Point PortBay at your gemini binary
- Connect the board over MCP (optional)
- Write a card and assign Gemini
- Move the card to To Do
Install PortBay
Homebrew installs the app and the bundled portbay CLI. Prefer a direct download? Grab the DMG from GitHub Releases and drag PortBay.app into Applications.
brew tap portbay-app/portbay && brew install --cask portbayAdd your project
Click Add project, pick the folder, and confirm the detected stack, hostname and port. Start it, and the project answers at its own .test URL over HTTPS with its database attached.
portbay add ~/code/myappPoint PortBay at your gemini binary
PortBay looks for gemini on your PATH and shows it in the agent picker when it finds it. If you installed it somewhere unusual, set the path by hand. PortBay ships no model of its own — it runs your install, on your Google account.
which geminiConnect the board over MCP (optional)
Settings → Integrations writes a project-scoped .gemini/settings.json with an mcpServers entry pointing at the bundled portbay-mcp binary. A connected session can then read the board, claim cards and advance them without you moving anything.
.gemini/settings.json → mcpServers.portbayWrite a card and assign Gemini
Brief it the way you would brief a teammate. Assign Gemini on the card, or set it as the board default so every unassigned card uses it. The card is a plain Markdown file in your repo.
.portbay/tasks/add-sitemap-route.mdMove the card to To Do
Auto-dispatch spawns the run immediately; manual mode queues it for your confirmation. The agent works, comments what it changed, appends to .portbay/HANDOFF.md and advances the card. Open the URL and judge the running app.
https://myapp.testThe same queue, in terminal tabs
Gemini's -p flag is easy to script, which is exactly why the runs outnumber your memory of them within an afternoon.
The board gives each run its own worktree and its own card, so the record of what changed outlives the scrollback.
# three tasks, three tabs, one repocd ~/code/myapp && gemini -p "add the sitemap route"cd ~/code/myapp && gemini -p "fix the 500 on /import"cd ~/code/myapp && gemini -p "paginate the orders API" # same working tree for all three — they overwrite each other# and nothing records which prompt produced which change
The pieces underneath
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 →Agent dev environment
Stack detection, runtimes, HTTPS, databases and mail, provisioned per project — the running app your agents verify their work against.
Explore →Asked before downloading
As a headless subprocess: `gemini -p "<the card>"`, with the working directory set to the project folder. It uses the gemini install already on your Mac and your existing Google account — PortBay ships no model and proxies no request.
Yes. Gemini is one of four agents PortBay wires both ways — Claude Code, Codex, Cursor and Gemini. Settings → Integrations writes a project-scoped .gemini/settings.json with an mcpServers entry for the bundled portbay-mcp binary, and a connected session can read cards, claim one and move it to Done.
Yes. Gemini is one of the agents whose model flag is wired, so a model chosen on the card is appended as `-m <model>`. Leave it unset and Gemini uses its own default.
Yes. Assign an agent per card, or set a board default for the rest. PortBay recognizes eleven agents out of the box and adds a Custom option that runs any other CLI from a command template, so a mixed board is the normal case rather than the exception.
Give your projects and your agents a real local home.
Download for macOSFree & open source · macOS 11+ on Apple Silicon · Pro from $10/mo