taw-fleet

A terminal dashboard for every TAW site on your Mac and its production copy: what it is, how to install it, and its settings.

taw-fleet finds the TAW themes in your Local by Flywheel sites and shows them in one terminal screen. You see which sites run, which themes are behind on taw/core, what's uncommitted or unpushed, and whether a classic theme still matches the taw-theme scaffold. With a few settings it also shows each production site, its pull requests and deploys, and the client's open BugSmash comments.

From the dashboard you open a theme in your editor, update it, hand work to Claude Code in the theme folder, or create a new site. Everything it does also runs on the command line.

Dashboard and keys

The cards and columns, every key, the action palette, skills, updating and new sites.

Command reference

Every command and flag, the JSON output, the doctor codes, Keychain items and files.

Production, pull requests and deploys

live, pulling content, wp-remote, merging and deploys, BugSmash.

Install

taw-fleet runs on macOS, Apple silicon or Intel.

brew install Relmaur/tap/taw-fleet

Update with brew upgrade taw-fleet. It installs two commands: taw-fleet, and taw, which runs a theme's own vendor/bin/taw with its site's PHP (taw-fleet 1.17.0+).

self-update refuses a Homebrew install and tells you to run brew upgrade taw-fleet. When a newer release is out, the dashboard shows ▲ <version> next to its own version.

First run

Check the fleet

taw-fleet doctor

You see every TAW site with what needs attention, most serious first, each with its fix: taw/core behind, uncommitted changes, unpushed commits, a broken symlink, a missing PHP build. doctor only reads.

Open the dashboard

taw-fleet

It opens in a new window of your terminal and gives the current one back. Press ? for every key and symbol.

Keep it in this terminal, if you prefer

taw-fleet --window=false

Or set window = false in the settings. When taw-fleet can't open a window, it says why and opens the dashboard where you are. When the output isn't a terminal (piped, CI), taw-fleet prints the list table instead.

How it finds sites

There is nothing to set up. taw-fleet reads Local's own files for the current user:

What	Where
Sites	`~/Library/Application Support/Local/sites.json`
Running or halted	Live from the Local app while it's open; otherwise Local's `site-statuses.json`
TAW themes	Each `wp-content/themes/*/composer.json` that requires `taw/core`. Symlinked themes are followed
taw/core installed and locked	The theme's `vendor/composer/installed.json` and `composer.lock`
Git state	`git` in the theme folder
Newest releases	GitHub tags of taw-core, taw-theme, taw-gutenberg and taw-fleet, cached for an hour

A theme named taw/gutenberg, or a wordpress-theme with theme.json and templates/, is a block theme. Any other TAW theme is classic.

The dashboard

One two-line card per TAW theme, with columns for taw/core, the scaffold check, production, BugSmash, pull requests, deploys and git. See Dashboard and keys.

Chat with Claude

> opens a chat with your own Claude Code, with taw-fleet's tools: about the whole fleet from the list, or one site from its details. Ask for anything TAW, from “what needs attention?” to “merge the update and deploy it”. It asks before it changes anything, with the dashboard's own question for an update or a merge. See Chat with Claude.

The fleet folder

~/TAW Fleet/ is where Claude works on the whole fleet. The chat's > from the list starts there, and so can claude in a terminal. taw-fleet init writes it, and the dashboard keeps it current every time it opens:

CLAUDE.md, made from your settings: how to work, the sites with a production copy, the fleet skills, and where things are. Your own notes go in CLAUDE.local.md, which taw-fleet never touches.
.mcp.json, so Claude has taw-fleet's tools there.
The fleet skills (fleet-check, update-fleet, onboard-mac), which ship with taw-fleet. See Fleet skills.

Your monthly reports are there too, in reports/.

A new site from a link

In the fleet chat (> from the list), ask for a site: “make me a site for a bakery”, or “make me this site:” followed by a link to a Claude design or artifact, a Figma file or an existing website. The new-site skill takes it all the way to a reviewed production site, and stops six times for you:

The brief. It reads the link into a brief: the pages and their sections, header and footer, colours and fonts, content and images, forms, classic or block theme, and its questions. You approve it or say what to change. It's saved in ~/TAW Fleet/sites/<slug>/, with screenshots of the reference.
The build. It creates the Local site (asking first), then the theme's build-site skill builds it on a branch, page by page, and runs the theme's checks.
Reference beside build. It screenshots the Local site and opens a page with the reference and the build side by side, desktop and mobile. Your corrections go back into the build.
GitHub. It puts the theme in a private repository (asking first) and waits for its CI.
Production. You pick the host; it sets up the deploy with the add-production skill. You get the host ready: WordPress on the domain, the content moved (WordPress's export and import, or the host's migration tool) and DNS. taw-fleet never copies a database. Merging the deploy pull request, after asking again, is the first deploy.
Live. It pins the site's companion key and links its BugSmash project (each asking first), screenshots production, and opens the launch report: what it did, the scores, and what's left for you.

You can stop after any stage ("just build it in Local") and pick up later. Images from someone else's website are replaced by placeholders unless you say they're the client's.

Update a theme

u in the dashboard, or taw-fleet update <site>, updates a site in one step. It runs the theme's own vendor/bin/taw update with the site's PHP and Local's Composer, after one question in the words of the theme's taw.json. On a new branch it updates taw/core, applies the framework files, runs the migrations and the checks, commits, and opens a pull request for you to merge. If a step fails, nothing is pushed, and you choose: Fix with Claude, or Do it myself from the same report.

U, or taw-fleet update --all, does the same for every client theme that needs it, one after another, each ending in its own pull request. No agent is involved.

All of it is on Dashboard and keys, with A and h (hand the update to Claude Code) and y and S (check and apply the taw-theme scaffold). What the update does inside the theme is on Updating a site.

Restore points

Before an update (u, U), a merge (M) and a content import (C), taw-fleet saves a restore point: the Local site's database, when the site runs, and the theme's branch and commit. A merge keeps only the branch, because it changes production, never your Local database. If the point can't be saved, the step doesn't run.

A restore point holds a full copy of a site's database, so taw-fleet keeps it where git and syncs can't reach it: ~/Library/Application Support/taw-fleet/restore/<site>/, readable only by you, compressed. Before saving, it checks that folder is outside the site, every theme and any git repository, and refuses otherwise. The copy goes straight from wp db export into that file: no .sql file is ever written in a site or a theme.

z in the dashboard asks which point to put back, then asks again before it does: the theme goes back onto the point's branch (commits made since stay) and the database is replaced by its copy. The site's details list the newest points in a RESTORE section.
After an update stops, a third choice joins Fix with Claude and Do it myself: 3 Put it back, the point from just before the update.
A restore can be undone: it saves how things are now as a new point first.
taw-fleet keeps the newest 5 per site. restore_keep in the settings changes that; 0 makes none.

taw-fleet restore awesome-company          # the points, newest first
taw-fleet restore awesome-company latest   # put the newest back (asks first)
taw-fleet restore awesome-company --save   # one now

Create a site

n in the dashboard, or taw-fleet create, makes a Local site with a fresh classic or block TAW theme, built, activated and committed. The admin password is shown once. See Create a site.

Client feedback

The FB column, F, X and taw-fleet comments moved to BugSmash comments.

Pull requests and deploys

The PR and DEPLOY columns, M and taw-fleet merge moved to Pull requests and deploys.

Pull production content

C and taw-fleet pull moved to Pull production content.

Notifications

taw-fleet watch install sends a macOS notification when a deploy fails, a production site goes down, a client comments or an update is ready to merge. See Notifications.

Commands

Every command, flag and JSON shape is in the Command reference.

Settings

Everything is optional: taw-fleet works with no settings file. The file is ~/.config/taw-fleet/config.toml, or $XDG_CONFIG_HOME/taw-fleet/config.toml when that variable is set.

taw-fleet config init   # write a commented starter file (never overwrites)
taw-fleet config show   # the settings in effect and the apps found
taw-fleet config path   # where the file is
taw-fleet config icons nerd   # Nerd Font icons; symbols switches back
taw-fleet config open-at-login on   # the dashboard opens when you log in; off stops it

editor = "Cursor"
terminal = "Ghostty"
window = false
icons = "nerd"
github_owners = ["Relmaur", "awesome-agency"]

[create]
kind = "classic"
admin_user = "marco"
admin_email = "me@example.com"
php = "8.2.30"
web_server = "nginx"

[sites.awesome-company]
production_url = "https://awesomecompany.com"
notes = "Deploys from main."
bugsmash_project = "00000000-0000-4000-8000-000000000000"
tags = ["retainer", "es", "client:awesome"]

[sites.acme-studio]
github_account = "acme-studio"

Key	What it does	Checked when the file loads
`editor`	The editor for `e`, `w` and `open --editor`. Empty: the first installed of Cursor, Visual Studio Code, PhpStorm, Zed, Sublime Text, Nova. Names are case-insensitive; `code`, `vscode` and `sublime` work too	No. An editor that isn't installed is an error when you open something
`terminal`	The terminal for `t`, the dashboard's window, Claude Code and Vite windows. Empty: the first installed of Ghostty, iTerm2, Warp, kitty, Terminal. `iterm` works too. Warp can't run a script, so windows that run something open in Terminal instead	No, same as `editor`
`window`	`false` keeps the dashboard in the current terminal. Default `true`. `--window` on the command line wins	Must be a boolean
`open_at_login`	`true` opens the dashboard in its own window each time you log in to the Mac. Default `false`. `taw-fleet config open-at-login on` (or `off`) sets it and adds (or removes) the login agent; see Open at login	Must be a boolean
`icons`	`"symbols"` (the default): plain Unicode icons that work with any font. `"nerd"`: Nerd Font icons, for a terminal set to a Nerd Font. `taw-fleet config icons <set>` changes this line and keeps the rest of the file	Must be `"symbols"` or `"nerd"`
`report_from`	Who the monthly reports say prepared them. Empty: no name	No
`report_language`	The reports' language, `"en"` (default) or `"es"`. Also per site, under `[sites.<folder>]`	Must be `"en"` or `"es"`
`restore_keep`	How many restore points to keep per site. Default `5`; `0` makes none	Must be 0 to 50
`group_by`	How the dashboard groups the list: `"tag"`, `"kind"`, `"production"`, `"prefix:<name>"` (by the tags that start `<name>:`) or `"none"`. `=` picks it and saves it here	Must be one of those
`github_owners`	Your GitHub accounts and organizations. A theme whose repository belongs to another owner is marked `@account`	Must be a list of strings
`[create] kind`	`"classic"` or `"block"`: the default theme for new sites	Anything else is an error
`[create] admin_user`, `admin_email`	The default WordPress admin for new sites	No; checked when you create a site
`[create] php`	A PHP version Local has downloaded, such as `"8.2.30"`. Empty: Local's preferred	No; checked when you create a site
`[create] web_server`	`"nginx"` or `"apache"`, optionally with a version. Empty: Local's preferred	No; checked when you create a site
`[sites.<folder>] production_url`	The production site. Turns on the LIVE column, `P`, `C`, `live` and `wp-remote` for that site	Must start with `https://` or `http://`
`[sites.<folder>] notes`	Free text added to the update prompt `h` and `A` build	No
`[sites.<folder>] github_account`	The GitHub account the site's theme belongs to, when it isn't yours (for example before it has a remote)	No
`[sites.<folder>] bugsmash_project`	The site's BugSmash project id. Turns on the FB column, `F` and `X`. `taw-fleet comments projects` lists the ids	Must be a UUID
`[sites.<folder>] tags`	The site's tags, such as `["retainer", "client:awesome"]`. `T` in the dashboard and `taw-fleet tag` set them	Lower case letters, digits, `:`, `_`, `-`; up to 32 characters, 12 per site
`umbrella`	Unused since v1.12.0. It's still accepted so older files load	No

<folder> is the site's folder name in ~/Local Sites. Any other key is an error that names it (unknown keys: …). With a broken file, the dashboard still opens, but its shortcuts are off until you fix it.

To have the dashboard waiting for you when you log in to the Mac, turn on open_at_login:

taw-fleet config open-at-login on

This sets open_at_login = true in the settings and adds a login agent, ~/Library/LaunchAgents/com.relmaur.taw-fleet.login.plist. From your next login on, the dashboard opens in a new window of your terminal (terminal in the settings), even with window = false. Nothing opens right away. macOS may show a “Background Items Added” notice the first time, and lists the agent under System Settings → General → Login Items & Extensions.

In the dashboard, open the : menu and type login: the Open at login entry under Settings shows whether it's on, and enter toggles it.

taw-fleet config open-at-login with no value says whether it's on, and so does taw-fleet config show. To stop it:

taw-fleet config open-at-login off

If you change open_at_login in the file by hand, the dashboard's next start adds or removes the agent to match. After a Homebrew upgrade the agent keeps working, because it runs Homebrew's taw-fleet link.

Nerd Font icons

The header, the detail pane's sections, the : palette's groups and the update screens carry icons. To use Nerd Font icons, install a Nerd Font and choose it in your terminal (Terminal: Settings → Profiles → Text), then switch:

brew install --cask font-jetbrains-mono-nerd-font
taw-fleet config icons nerd

taw-fleet config icons with no value shows the set in effect. If icons show as empty boxes, the terminal isn't using a Nerd Font: run taw-fleet config icons symbols.

Where updates are delivered

Updates push to the origin remote, or to the one the theme's taw.json names in update.remote (taw/core 1.92.0+). taw-fleet reads pull requests and deploys from that remote's repository, M pulls from it after a merge, and doctor's git findings name it. When that remote isn't origin, M also fast-forwards origin's default branch to the merge, so the copy stays in step (see Merge a pull request).

Other GitHub accounts

A theme of another GitHub account shows @account in the GIT column and the detail pane, and /other filters to those themes. taw-fleet marks a theme when one of these is true:

Its remote uses an SSH host alias such as github.com-acme, the usual way to use a second account.
Its repository's owner isn't in github_owners. Without github_owners, this rule is off.
The site sets github_account, for example for a theme inside a larger repository.

An account listed in github_owners is never marked.

Troubleshooting

Was this page helpful?