From b4275b909b0f0083557a43740b0915f898cbf8b4 Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Sun, 19 Apr 2026 21:21:54 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20document=20xcodebuildmcp?= =?UTF-8?q?=20upgrade=20command?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a concise "Keeping the CLI up to date" section to the CLI page covering the new `xcodebuildmcp upgrade` command, its `--check` and `--yes` flags, the npx caveat, and the non-interactive exit behavior. Update the Installation page to point at the self-update command instead of repeating per-channel upgrade instructions. Also record an Audience and voice rule in CLAUDE.md: docs are for end users of XcodeBuildMCP, not contributors working on the implementation, so drafts should focus on usage and user-impacting behavior rather than internal mechanics (per-channel lookup strategies, fetch/parse details, timeouts, etc.). The revised upgrade docs follow this rule. Co-Authored-By: Claude --- CLAUDE.md | 6 ++++++ app/docs/_content/cli.mdx | 15 +++++++++++++++ app/docs/_content/installation.mdx | 16 ++++++++++------ 3 files changed, 31 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 34f0ac7..b3d8177 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,12 @@ Placement rules when writing or moving content: - Frame public docs by user visible outcome, not implementation. Never leak source code literals (for example `{ sentry: true }` in server code, internal type names, private function names) into public pages. - When a spec feature is part of the public MCP response, it belongs in public docs regardless of how MCP literate the reader is. +### Voice + +- Write about what the command or feature does for the user and when to use it. Skip the "how it works" details: which APIs are called, what the lookup strategy is, internal fallbacks, file layouts, timeout values, protocol specifics, parsing rules. +- Keep callouts and notes focused on things that affect the user's decisions (when to use a flag, when something will not work for them), not on justifying the implementation. +- If you find yourself writing a per-channel mechanics table, a "fetched from ... by ..." sentence, or a "we chose X because Y" explanation, cut it. + ### Adding or editing a page Content lives at `app/docs/_content/.mdx`. To add a new page, also update: diff --git a/app/docs/_content/cli.mdx b/app/docs/_content/cli.mdx index 4ccb42a..cad4166 100644 --- a/app/docs/_content/cli.mdx +++ b/app/docs/_content/cli.mdx @@ -27,6 +27,7 @@ xcodebuildmcp simulator build --help | `tools` | List every tool, grouped by workflow. | | `setup` | Interactive wizard to create or update `.xcodebuildmcp/config.yaml`. | | `init` | Install the MCP or CLI agent skill (Claude Code, Cursor, Codex). | +| `upgrade` | Self-update the CLI using the package manager it was installed with. | | `simulator` | Build, install, launch, test, log capture on simulators. | | `device` | Install, launch, test on physical Apple devices. | | `macos` | Build, run, test macOS targets. | @@ -176,6 +177,20 @@ For agents driving long operations through the shell, `jsonl` is usually the rig See Output Formats for the envelope and event shapes. +## Keeping the CLI up to date + +Run `xcodebuildmcp upgrade` to check for a newer version and install it in place. No need to remember whether you installed via Homebrew or npm, the command figures that out and runs the right upgrade for you. + +```shell +xcodebuildmcp upgrade # show current vs latest, release notes, and confirm +xcodebuildmcp upgrade --check # just tell me if there's an update, don't prompt +xcodebuildmcp upgrade --yes # upgrade without asking +``` + +If you installed via `npx`, the command will tell you how to pick up the latest version the next time you invoke it (npx installs are ephemeral, so there's nothing to upgrade in place). + +In CI or other non-interactive contexts, pass `--check` or `--yes`. Without either flag in a non-TTY context, the command exits non-zero instead of hanging on a prompt. + ## Per-workspace daemon Some XcodeBuildMCP tools need to keep state between commands (for example log capture, video recording, LLDB debugging, and background Swift Package runs). To do that, XcodeBuildMCP uses a background process. diff --git a/app/docs/_content/installation.mdx b/app/docs/_content/installation.mdx index 3bd9561..74c7609 100644 --- a/app/docs/_content/installation.mdx +++ b/app/docs/_content/installation.mdx @@ -22,12 +22,6 @@ brew tap getsentry/xcodebuildmcp brew install xcodebuildmcp ``` -Upgrade later: - -```shell -brew update && brew upgrade xcodebuildmcp -``` - ## Option B: npm / npx For CLI use, install globally: @@ -41,6 +35,16 @@ For MCP-server-only use, no global install needed, just reference `npx` in your Pin a specific version by replacing `@latest` with a tag, for example `@2.3.2`. +## Keeping it up to date + +Once installed, run the built-in self-update command: + +```shell +xcodebuildmcp upgrade +``` + +It checks for a newer version and installs it in place using whichever package manager you installed with. See [CLI → Keeping the CLI up to date](/docs/cli#keeping-the-cli-up-to-date) for available flags. + ## Verify Run the doctor to check your environment: