taw-fleet command reference

taw-fleet on its own opens the dashboard. Every command below also takes -h or --help.

Global flags

There is no --version flag: use taw-fleet version.

Naming a site

<site> is the site's folder name in ~/Local Sites, its name in Local, its domain (with or without .local), its Local id, or one of its TAW theme folders. Names, domains and theme folders are matched without regard to case. A term that matches several sites is an error that lists them.

When a site has several TAW themes, commands that work on a theme take --theme <folder>. Naming a theme folder as <site> picks that theme too.

Output, questions and exit codes

• Output is colored in a terminal and never when piped. --json output is never colored.
• Commands that change something ask first ([y/N]). Without a terminal they refuse with “not a terminal: add --yes to confirm”, so a script never changes a site by accident. --yes (or -y) skips the question.
• Progress goes to stderr, the summary to stdout.
• The exit code is 0 on success and 1 on an error. wp exits with wp-cli's own code. doctor exits 0 whatever it finds: read its findings, or its JSON.

JSON output

Only these commands take --json:

A Finding is { "severity": "error" | "warn" | "info", "code", "site_id", "site", "theme", "message", "fix" }. A Site carries its Local details, its themes (each with core, git, drift, github, account, skills_missing…; git.remote is taw.json's delivery remote when it isn't origin, git.foreign_upstream the other repository a branch tracks), and production and feedback once they've been read. taw-fleet show <site> --json is the quickest way to see every field.

Commands at a glance

Look at the fleet

list

taw-fleet list [--all] [--json] [--tag <tag>]

The Local sites that have a TAW theme, with their status, themes, kind, taw/core, git, domain and tags.

tag

taw-fleet tag <site> [tag…] [--add <tag>] [--remove <tag>] [--clear] [--yes]

With only the site, prints its tags. With tags, sets them, replacing the old ones. --add and --remove change a few; --clear removes them all. A tag is lower case letters, digits, :, _ or -, up to 12 per site. Asks first; --yes doesn't. The dashboard's #. See Tags and groups.

notes

taw-fleet notes <site> [text…] [--by you|claude] [--last N] [--json] [--path]

With only the site, prints its notes, newest first. With text, adds a note (- reads it from stdin). Adding doesn't ask: a note only goes into ~/TAW Fleet/sites/<site>/notes.md. note works too. The dashboard's N. See Site notes.

Put -- before a note that starts with -: taw-fleet notes acme-shop -- "-50% sale page is live".

show

taw-fleet show <site> [--json]

One site in full: Local, its themes, production, BugSmash, its findings and its five newest notes (notes in the JSON).

doctor

taw-fleet doctor [site] [--json]

Every TAW site, or one, with what needs attention, most serious first, each with its fix. It only reads. Production, BugSmash and pull requests are included unless --offline. See Doctor finding codes.

refresh

taw-fleet refresh

Everything the dashboard shows, read again for every site, past the caches (the dashboard's ctrl+r): the Local sites with the newest versions from GitHub, the pull requests, CI and deploys, the production sites, the BugSmash comments, and the scaffold check of every classic theme. It writes nothing but taw-fleet's own cache. No flags.

Open and work

open

taw-fleet open <site> [flags]

With no flag, opens the theme in your editor. Several flags open several things.

work

taw-fleet work <site> [--stop] [--theme <folder>] [--yes]

Starts the site when it's stopped, opens the theme in your editor, runs Vite (npm run dev, or pnpm or yarn) in its own terminal window, and opens the site once Vite answers. The dashboard's w.

start, stop, restart

taw-fleet start <site> [--yes]
taw-fleet stop <site> [--yes]
taw-fleet restart <site> [--yes]

Through the Local app, which must be open. Each waits until the site is up or down, up to three minutes. Before it acts, it looks for Local's leftover processes in the way and names them instead of trying against them (see unstick).

unstick

taw-fleet unstick <site> [--yes]

After a lot of starting and stopping, Local can leave nginx or php-fpm workers behind whose master is gone. They hold the site's PHP socket, its port, or the router's ports 80 and 443, so the site hangs or Local reports a port conflict. unstick lists them and ends them after asking. It only touches Local's own nginx and php-fpm whose parent is gone.

wp

taw-fleet wp <site> [wp-cli arguments]

wp-cli with the site's PHP, Local's wp-cli and the site's MySQL socket. Everything after the site goes to wp-cli unchanged, flags included, and wp-cli's exit code is kept.

taw-fleet wp john-seed option get stylesheet
taw-fleet wp taw plugin list --format=json

Theme tools

These run the theme's own tools with the site's PHP and Local's Composer. sync, update and handoff refuse the umbrella's own taw-theme and taw-gutenberg; update --all and handoff --all leave them out.

sync

taw-fleet sync <site> [--apply] [--json] [--theme <folder>] [--yes]
taw-fleet sync --all

Runs the theme's php bin/taw sync: compares its framework files (Tier 1) and docs and config (Tier 2) with the newest taw-theme. Read-only unless --apply. For classic themes with bin/taw only.

update

taw-fleet update <site> [--theme <folder>] [--yes]
taw-fleet update --all [--yes]

Runs the theme's own vendor/bin/taw update with the site's PHP and Local's Composer, after one question worded from the theme's taw.json. On a new branch it updates taw/core, applies the framework files (classic themes), runs the migrations and the checks, commits, and opens a pull request (or what taw.json's deliver says). It asks nothing after the first question. See Update a theme.

• It refuses a theme that isn't a git repository, has uncommitted changes, or isn't on its default branch, before anything runs.
• A theme on taw/core older than 1.91.2 first gets the newest taw/core in vendor/ (its composer.lock goes back), so its first update is one step too.
• If a step fails, nothing is pushed: the theme's .taw/update-report.md says what failed and how to finish it. In the dashboard, u offers Fix with Claude on the same report.
• Progress goes to stderr, the summary to stdout. It exits 1 when the update stops or doesn't start.

inspect

taw-fleet inspect <site> [--json] [--theme <folder>]

Runs php bin/taw inspect --json against the site's database: its blocks, fields and forms. The site must be running, and the theme must have bin/taw.

handoff

taw-fleet handoff <site> [--copy] [--launch] [--out <file>] [--theme <folder>]
taw-fleet handoff --all [--launch]

Prints the prompt that hands the theme's update to Claude Code: the update-theme skill, where everything is on this Mac, what taw-fleet found, and the rules (work on a chore/taw-core-<version> branch, Tier 2 changes need your OK, ask before pushing).

create

taw-fleet create [name] [flags]

Creates a Local site, installs taw-theme (classic) or taw-gutenberg (block) into it with taw-create, builds its assets, activates it and makes the theme a git repository with a first commit. The admin password is generated and shown once. Local must be open.

In a terminal, anything missing is asked in a form. Otherwise give the name, --classic or --block, --admin-user, --admin-email (or set them in the [create] settings) and --yes.

taw-fleet create "Acme Shop" --classic --php 8.2 --admin-user marco --admin-email me@example.com --yes

Production

See Production, pull requests and deploys for how these work.

live

taw-fleet live [site] [--logs <n>] [--json]

Asks each production site's companion for its health: WordPress, PHP, taw/core and companion versions, plugin updates, known vulnerabilities and recent taw/core log lines. Sites come from production_url. It always asks the sites now, past the cache.

pull

taw-fleet pull <site> [--theme <folder>] [--yes]

Fetches the production site's published content through its companion (0.4+), previews the import into the Local site, then imports it after you confirm. Starts the Local site when it's stopped. The dashboard's C.

publish

taw-fleet publish <site> [--theme <folder>] [--no-review] [--json] [--decisions <file>] [--yes]
taw-fleet publish undo <site> [--journal <file>] [--yes]
taw-fleet publish history <site> [--json]

Compares the Local site's content with production's (the base a pull or the last publish saved), asks production what publishing would change, and opens the review in your browser. Nothing is written until you press Publish there. Needs taw/core 1.98+ and companion 0.5+ on production, with "publish": true in the theme's composer.json. The dashboard's p. See Publish content to production.

publish undo says what undoing the last publish would do, then asks (the dashboard's x). --journal picks an older one. publish history lists the site's publishes, newest first, each with its kept review.

wp-remote

taw-fleet wp-remote <site> <GET|POST|PUT|PATCH> <rest-route> [--data <json>] [--file <path>] [--type <mime>]

Calls the production site's WordPress REST API as its bot user. The answer's JSON goes to stdout; a WordPress error exits non-zero with its code and message. There is no DELETE.

prs

taw-fleet prs [site] [--json]

For every TAW theme with a GitHub repository: its open pull requests with their CI, and its deploy workflow (the commit production has, a deploy running or failed, the commits not deployed yet). Needs a GitHub token.

merge

taw-fleet merge <site> [--pr <number>] [--theme <folder>] [--yes]

Merges an open pull request with the repository's default merge method, deletes its branch, and pulls the default branch into the local theme when its tree is clean. Refused for a draft, a conflict, or CI that failed or still runs. Merging a client theme deploys its production site.

comments

taw-fleet comments [site] [--json]

The open comments in each site's BugSmash project, newest first: the count and the oldest's age, then the three newest per site (the five newest when you name one site). Sites come from bugsmash_project. It only reads. To resolve them, use the theme's resolve-comments skill (X in the dashboard).

watch

taw-fleet watch [--once] [--json] [--no-notify] [--every 5m]

Checks the fleet and tells you, once, with a macOS notification, what changed since the last check: a failed deploy, CI failing on the default branch, a production site down (two checks in a row) or back, a site that answered without its pinned key's signature, new BugSmash comments, an update's pull request ready to merge. Clicking a notification opens the dashboard on its site. The first check only notes what it sees. Alone, it checks every 5 minutes in this terminal. See Notifications.

Event kinds in --json and watch status --json: deploy.failed, ci.failed, production.down, production.up, production.unverified, comments.new, pr.ready, report.ready.

ready

taw-fleet ready [site] [--json]

The SETUP checklist from the dashboard's details, for one site or every client site: repository, secrets check, deploy, production, companion, bot, BugSmash, skills. Each step says what's there, or how to do it. See Set up a site.

repo

taw-fleet repo <site> [--owner <account>] [--name <repo>] [--theme <folder>] [--yes]

For a theme with no GitHub repository: creates a private one (default name <theme folder>--theme; default owner the first of github_owners, else your gh account), adds it as origin, pushes the default branch and the current one, and requires the dump check (ci / committed-files) on the default branch. Asks first. Needs gh signed in.

deploy

taw-fleet deploy setup <site>                 # the form: host, details, key, test, apply
taw-fleet deploy profiles [--json]            # the hosts taw-fleet knows, and where each value is
taw-fleet deploy key <site>                   # the deploy key's public half (made the first time)
taw-fleet deploy test <site> [target flags]   # connect as the deploy will; nothing changes
taw-fleet deploy apply <site> [target flags] [--yes]

Sets up taw/core's shared deploy (taw/core 1.97+) for a theme on GitHub with no deploy yet: by SSH + rsync into the theme's folder on the server, or by git push to the host's remote. apply tests the connection again, pinning the server's host key, then (after asking) stores the settings as repository variables and the key as the secret DEPLOY_SSH_KEY, opens a pull request adding .github/workflows/deploy.yml (merging it deploys), and adds production_url to the settings. The deploy key stays in the Keychain only until then.

launch-report

taw-fleet launch-report <site> [--theme <dir>] [--open] [--json] [--no-speed]

Checks a site in production as it is now, only reading it, and saves its launch report as ~/TAW Fleet/sites/<site>/launch.html (and launch.md). The checks: production answers over HTTPS, http:// moves to https:// for good, the certificate; search engines are let in (no noindex in the page or its headers, which is what WordPress's "Discourage search engines" leaves behind, and a robots.txt that doesn't shut everyone out); the last deploy; the companion (verified, the same taw/core as the theme, plugin updates, known vulnerabilities); PageSpeed, mobile and desktop (up to a minute; --no-speed skips it); taw-fleet watch; BugSmash; and the rest of the SETUP checklist. The report starts with what's left for you, each with how. PageSpeed's picture of production's first screen is saved in production/, beside the Local build's from build/ when there is one. --json adds report, the page's path.

restore

taw-fleet restore <site> [point] [--yes] [--save] [--json]

A site's restore points, newest first. Each holds the Local database (when the site was running) and the theme's branch and commit, saved before an update, a merge (branch only) or a content import, or by hand with --save. With a point (its id, or latest) it puts it back after asking: the theme onto the point's branch, commits made since staying, and the database from its copy. How things are just before is saved as a point first, so a restore can be undone. See Restore points.

Points live in ~/Library/Application Support/taw-fleet/restore/<site>/. taw-fleet refuses to save one when that folder is inside the site, a theme or any git repository, and the step that wanted it doesn't run.

report

taw-fleet report <site> | --all [--month 2026-09] [--language en|es] [--print] [--json] [--open] [--no-speed]

Makes a site's monthly report: availability (from watch), updates and changes, BugSmash comments, PageSpeed, and the live site's security and maintenance. It saves Markdown and HTML in ~/TAW Fleet/reports/<site>/<month>.{md,html} and prints a summary, including why a section couldn't be measured. Without --month, it's this month so far. See Monthly reports.

chat

taw-fleet chat [site] --prompt [--theme <dir>]

The chat itself is in the dashboard: > from the list for the whole fleet, > on a site's details for that site. See Chat with Claude. --prompt prints what taw-fleet adds to Claude's instructions, for the fleet or a site, so you can read it or give it to another agent.

init

taw-fleet init

Writes the fleet folder, ~/TAW Fleet/: a CLAUDE.md made from the settings, taw-fleet's MCP server in .mcp.json, and the fleet skills. It lists what it wrote, or says it's already up to date. The dashboard does the same when it opens. Your CLAUDE.local.md, your own skills and the reports are left alone.

Settings and taw-fleet

config

Every key is on the taw-fleet page.

self-update

taw-fleet self-update [--check] [--yes]

Downloads the newest release for this Mac from GitHub, checks it against the release's checksums.txt and replaces this binary. A Homebrew install is refused: run brew upgrade taw-fleet.

version

taw-fleet version

Prints taw-fleet <version> (<commit>).

completion

taw-fleet completion <bash|zsh|fish|powershell> [--no-descriptions]

Prints a shell completion script. taw-fleet completion <shell> --help shows how to load it. --no-descriptions leaves out the descriptions.

Doctor finding codes

Codes are stable and dot-namespaced, so scripts can filter doctor --json on them. Severities show as ✗ error, ▲ warning and • note (info in JSON).

Keychain items

taw-fleet keeps its secrets in your login Keychain, under the service taw-fleet. They're never written to a file or shown again.

Each Mac needs its own copy.

Environment variables

Files

With XDG_CONFIG_HOME set, the two config files live in $XDG_CONFIG_HOME/taw-fleet/. With TAW_FLEET_HOME, every path is under that folder instead of your home.