From 2e36681deec5a5e2a6d5a357aecd2d028d47fd08 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 | 7 +++++++ app/docs/_content/cli.mdx | 15 +++++++++++++++ app/docs/_content/installation.mdx | 16 ++++++++++------ 3 files changed, 32 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4c818d4..a93508c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,6 +4,13 @@ ## Docs site +### Audience and voice + +- These docs are for end users of XcodeBuildMCP (developers using the CLI and MCP server in their workflow), not contributors working on XcodeBuildMCP itself. +- 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 da7a471..c2d7ea5 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. | @@ -119,6 +120,20 @@ xcodebuildmcp simulator record-video \ Every command accepts --output json for JSONL event streams, suitable for CI pipelines and scripting. +## 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 The CLI auto-starts a daemon only when needed. Stateless tools (`build`, `test`, `list`, discovery) run in-process. Stateful tools route through the daemon: 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: