Production, pull requests and deploys

taw-fleet reads each production site through the TAW companion, a small plugin that ships with every TAW theme. It also reads GitHub for pull requests and deploys, and BugSmash for the client's comments. Each part turns on with a setting for the site, in [sites.<folder>] of the settings file.

Check production

taw-fleet live asks each production site's companion how the site is doing: WordPress, PHP, taw/core and companion versions, plugins with updates waiting, known vulnerabilities from the site's scanner (Defender or Wordfence), and recent taw/core log lines. In the dashboard, that's the LIVE column and the detail pane's LIVE section. doctor adds the live.* findings.

How it's secured

Every request is a signed GET to the companion's /wp-json/taw-hub/v1/ routes: health, inventory, vulnerabilities and logs, and content for a pull. Nothing is written on the site.

• Requests carry taw-fleet's Ed25519 signature. The key lives in your macOS Keychain, never in a file. A site answers only when it trusts that key's public half.
• Answers carry the site's own signature. taw-fleet checks it against the key you pinned for the site, like SSH's known_hosts. Pinned keys live in ~/.config/taw-fleet/companion-keys.json.
• An answer from a site with no pinned key is shown but not trusted: ◐ in the LIVE column and a live.untrusted note. A signature that doesn't match the pinned key is a live.signature error.

Set it up

[sites.awesome-company]
production_url = "https://awesomecompany.com"

taw-fleet live key new
taw-fleet live key show

taw-fleet live trust awesome-company

taw-fleet live awesome-company --logs 20

taw-fleet live always asks the sites now. The dashboard, doctor and show reuse an answer for 5 minutes; L in the dashboard asks again. Log lines are never cached.

When a site doesn't answer

Pull production content

C in the dashboard, or taw-fleet pull <site>, copies a production site's published content into its Local copy: posts and custom post type entries, TAW fields and options, terms, and the media they use. Drafts, users, comments and settings never come over.

It needs companion 0.4+ on production with taw/core's Content Interchange, and a Local theme with bin/taw and content:import.

To undo the last import, run taw content:import --undo in the theme folder to preview it, then again with --yes.

pull --yes skips both questions. Pull refuses the umbrella's own taw-theme and taw-gutenberg. A site with no pinned key is refused: run taw-fleet live trust <site> first.

After a successful import, taw-fleet keeps the snapshot as the site's base: production's content as Local last had it. Publishing compares with it to know what changed on each side.

Publish content to production

p in the dashboard, or taw-fleet publish <site>, sends what changed in the Local site's content to production: pages, posts and custom post type entries, TAW fields and options, terms, menus, and the media they use. Users, comments and site settings never go. You see every value that would change, field by field, and nothing is written until you press Publish.

Turn it on for a site

Publishing is off until the site's theme asks for it, through a reviewed commit and a deploy.

"extra": { "taw-companion": { "keys": { "taw-fleet": "…" }, "publish": true } }

The details' PUBLISHED section says what's still missing. Once publishing is ready, it lists the last publishes, the newest with the path of its review.

How a publish goes

Undo a publish

x in the site's details, or taw-fleet publish undo <site>, first says what undoing the last publish would do (“put back 4 values and delete 1 record it created”), then asks. A value goes back only where it's still what the publish wrote: an edit made on production since is kept and listed. A record the publish created is deleted unless it was edited since. --journal undoes an older publish; taw-fleet publish history <site> lists them.

Without a browser

taw-fleet publish acme --no-review                 # print the review
taw-fleet publish acme --no-review --json          # the review as JSON, with the record and change keys
taw-fleet publish acme --no-review --yes           # publish as reviewed; refuses while a value changed on both sides is undecided
taw-fleet publish acme --decisions choices.json --yes

choices.json names the records to publish and the side that wins each value changed on both sides (keep = production's, take = Local's):

{"include": ["post:page:about"], "sides": {"post:page:about": {"fields.hero_heading": "take"}}}

A picture's details go only when named, by their key: "include": ["media:2026/09/team.webp"].

In the chat, Claude publishes through the publish_content tool: it describes the changes, asks you about each value changed on both sides, then asks before publishing.

How publishing is secured

• Every request is signed with the fleet key, and every answer is checked against the site's pinned key.
• The one-time token works once, for one plan. Production writes only the records you approved, as you reviewed them.
• Production accepts only the files the plan named, matched by their sha256. It never downloads anything from your Mac.
• Limits: 32 MB per file, 512 MB and 500 files per publish, one publish at a time.
• Every step is logged on production (content.publish.*; taw-fleet live <site> --logs 20 reads them).
• No database copy is made or sent. The base is a content snapshot, kept in ~/Library/Application Support/taw-fleet/content/, outside every site, theme and git repository.

Write to production

Site skills that change the live site, like resolve-comments, write through taw-fleet wp-remote. It calls the site's WordPress REST API as a bot user whose Application Password stays in your Keychain, so it never appears in a Claude transcript or a file. Setting up the bot is on Site skills.

taw-fleet wp-remote awesome-company GET '/wp/v2/pages?slug=nosotros&context=edit'
taw-fleet wp-remote awesome-company POST /wp/v2/pages/12 --data @meta.json
taw-fleet wp-remote awesome-company POST /wp/v2/media --file hero.webp

• Methods: GET, POST, PUT and PATCH. There is no DELETE: taw-fleet never deletes on production.
• Body: --data takes inline JSON, @file, or - for stdin. --file uploads a file as the body, with its type from the extension or --type. The two can't go together.
• URL: each request uses the ?rest_route= form, because some hosts' firewalls block /wp-json/wp/v2/users. It uses HTTP/1.1, and retries an empty, unreadable or server-error answer up to twice, a second apart.
• Output: the JSON answer goes to stdout. A WordPress error exits non-zero with its code and message.
• Credentials: wp-remote key import <site> reads user:application password from stdin into the Keychain item wp-<folder>. wp-remote key show <site> says which bot is stored and checks it against the site, showing its name and role.

Pull requests and deploys

With a GitHub token, the dashboard shows each theme's open pull requests and its deploy. taw-fleet uses GITHUB_TOKEN or GH_TOKEN, else gh auth token. Without a token, the PR and DEPLOY cells show ?. Run gh auth login.

The repository is the one behind the theme's delivery remote: origin, or the remote the theme's taw.json names in update.remote (taw/core 1.92.0+), for a site whose production deploys from another organization. It's the same remote the update pushes to and opens its pull request on.

• Pull requests: up to 20 open ones per repository, with their CI result and whether they conflict.
• Deploy: the repository's active workflow whose file name starts with deploy. Production “has” the commit of its newest successful run. A skipped or cancelled run isn't a failure.

The columns refresh every 5 minutes, every 15 seconds while a deploy runs, and right after an update opens a pull request. L refreshes them now. taw-fleet prs shows the same, with the commits not deployed yet. doctor adds pr.ready, pr.failing, pr.conflict, deploy.failed, deploy.blocked and deploy.pending.

Merge a pull request

M in the dashboard, or taw-fleet merge <site>, merges a theme's pull request. In the dashboard, several sites can merge at once, also while an update runs: each merge runs on its own, and a site that's still merging refuses a second M.

1. Pick. With several open, the dashboard asks which, by number. On the command line, use --pr <number>.

2. Refusals. A draft, a conflict, CI that failed, and CI that still runs are refused, each with the reason.

3. Ask. The question names what the merge does: “Merge #12 “Hero copy” into main? CI passed. This deploys https://awesomecompany.com (production).” When taw.json delivers to another remote, it adds: “Then origin (the copy) gets main too, when it can follow.”

4. Merge. taw-fleet uses the repository's default merge method for you, and only if the branch is still at the commit taw-fleet read. If someone pushed since, it stops: refresh with L and look again.

5. Clean up. It deletes the branch on GitHub, when the branch is in the same repository. If the local theme has no changes to tracked files and is on that branch or the default one, it switches to the default branch, pulls it (from the delivery remote, when taw.json names one), and deletes the local branch. Untracked files, such as the update's .taw/ report, don't stop it. Otherwise it leaves the theme alone and says why.

   After that pull, when the delivery remote isn't origin, it runs git push origin <default>:<default>, a fast-forward only, so origin stays a copy of the merge. If origin's default branch has commits of its own, it's left alone, and the summary says to realign it once (git push --force-with-lease origin <default>, after checking it has nothing the other repository lacks).

6. Follow the deploy. The dashboard checks GitHub every 15 seconds for up to 30 minutes. It says when production has the merge and how long it took, or that the deploy or CI failed, with the run's link. Then it checks the live site again.

7. Remind you about the page cache. While the deploy runs, the MERGE section says to clear the page cache once production has the merge, not before. Once it does, it says to clear it now (Hummingbird, WP Rocket, the host's cache). A cache cleared during the deploy is rebuilt from the old code, and the site keeps the old pages until it's cleared again. taw-fleet doesn't clear it for you.

While a site merges, its card says so on the theme line: a spinner with “merging #8…”, then “deploying…”. Afterwards the card keeps ✓ or ✗ for 15 minutes. The detail pane opens with a MERGE section that lists each step: merged (commit and time), this Mac back on the site's branch, deploying to the production host (elapsed time), then on production, with the time after the merge, or what failed. The bottom line lists every merge in progress.

BugSmash comments

Clients review their live site in BugSmash and pin comments to the page. taw-fleet shows them per site.

pbpaste | taw-fleet comments key import
taw-fleet comments key show

taw-fleet comments projects

[sites.awesome-company]
bugsmash_project = "00000000-0000-4000-8000-000000000000"

• FB column: how many comments are open, in the warning color once the oldest has waited more than two days. The second line shows the oldest's age.
• Detail pane: the FEEDBACK section quotes the three latest comments with their number, page, author and age.
• doctor: comments.open, comments.unreachable and comments.no-key.
• F: opens the site's review page in BugSmash.
• X: opens Claude Code beside the dashboard, in the theme folder, with the theme's resolve-comments skill. Its first message has the open comments, the project, the review page and the production URL, and asks it to show its plan first, ask before anything reaches production, and resolve a comment only once its change is live. X needs open comments and a theme with the skill (taw/core 1.89+). When Claude Code exits, the dashboard checks BugSmash again.
• taw-fleet comments: the open comments of every site, or one (--json for scripts).

taw-fleet only reads BugSmash, and caches each answer for 5 minutes (L asks again). Replying and resolving happen in the skill: see Site skills.

Monthly reports

m in the dashboard, or taw-fleet report <site>, makes a site's monthly report for its client. It's for you to read and send: taw-fleet never sends it.

A section taw-fleet couldn't measure says “Not available for this month” in the report. The terminal and --json say why.

report_from = "Marco Lizardo"   # "Prepared by …"; leave it out for no name
report_language = "en"          # or "es"

[sites.awesome-company]
report_language = "es"          # this client's reports in Spanish

pbpaste | taw-fleet report key import

On the 1st of each month (up to the 3rd, in case your Mac was asleep), taw-fleet watch makes last month's report for every production site it was watching, and a notification tells you it's ready.

taw-fleet report awesome-company --month 2026-09 --open
taw-fleet report --all --month 2026-09   # every production site
taw-fleet report awesome-company --print        # the Markdown only, nothing saved

Notifications

taw-fleet watch tells you when something needs you, even with the dashboard closed. It checks the fleet every 5 minutes and sends a macOS notification for each change, once.

taw-fleet watch install

taw-fleet watch test awesome-company

• Told once: each failed run, failing commit, new comment or ready pull request is told the first time it's seen. A check that can't reach GitHub, a site or BugSmash keeps what the last one saw, so old news doesn't come back after an outage.
• Clicking: opens the dashboard on the site through terminal-notifier, which the Homebrew cask installs. Without it, or with its notifications turned off, the notification still comes, through Script Editor, and clicking it doesn't open the dashboard.
• Uptime: each production site's checks are kept per day, for its monthly report.