From 95f24de9ad527e0dc075b423bf51c25b9e4de47c Mon Sep 17 00:00:00 2001 From: Dyan Galih Date: Fri, 26 Jun 2026 01:22:42 +0000 Subject: [PATCH 1/2] Docs: document missing flags --force and --refresh-shared-infra Fixes #3177 --- docs/reference/extensions.md | 1 + docs/reference/integrations.md | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md index 923d0b9b82..12d95d3182 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -25,6 +25,7 @@ specify extension add | Option | Description | | --------------- | -------------------------------------------------------- | | `--dev` | Install from a local directory (for development) | +| `--force` | Overwrite if already installed | | `--from ` | Install from a custom URL instead of the catalog | | `--priority `| Resolution priority (default: 10; lower = higher precedence) | diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index 5746382161..3c978e9157 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -101,6 +101,7 @@ specify integration switch | `--script sh\|ps` | Script type: `sh` (bash/zsh) or `ps` (PowerShell) | | `--force` | Force removal of modified files during uninstall; when the target is already installed, overwrite managed shared templates while changing the default | | `--integration-options` | Options for the target integration when it is not already installed | +| `--refresh-shared-infra` | Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved) | If the target integration is not already installed, equivalent to running `uninstall` followed by `install` in a single step. In this mode, `--force` controls whether modified files from the removed integration are deleted. If the target integration is already installed, `switch` only changes the default integration, like `use`; in this mode, `--force` controls whether managed shared templates are overwritten while the default changes. `--integration-options` is rejected for already-installed targets because changing integration options requires reinstalling managed files; run `upgrade --integration-options ...` first, then `use `. From 464deabbe05ba7d0321cacab5b2adacde05e4363 Mon Sep 17 00:00:00 2001 From: Dyan Galih Date: Fri, 26 Jun 2026 01:32:22 +0000 Subject: [PATCH 2/2] Address review: Reorder flags to match CLI help output --- docs/reference/extensions.md | 2 +- docs/reference/integrations.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md index 12d95d3182..90e5ab8747 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -25,8 +25,8 @@ specify extension add | Option | Description | | --------------- | -------------------------------------------------------- | | `--dev` | Install from a local directory (for development) | -| `--force` | Overwrite if already installed | | `--from ` | Install from a custom URL instead of the catalog | +| `--force` | Overwrite if already installed | | `--priority `| Resolution priority (default: 10; lower = higher precedence) | Installs an extension from the catalog, a URL, or a local directory. Extension commands are automatically registered with the currently installed AI coding agent integration. diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index 3c978e9157..c52ea719ff 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -100,8 +100,8 @@ specify integration switch | ------------------------ | ------------------------------------------------------------------------ | | `--script sh\|ps` | Script type: `sh` (bash/zsh) or `ps` (PowerShell) | | `--force` | Force removal of modified files during uninstall; when the target is already installed, overwrite managed shared templates while changing the default | -| `--integration-options` | Options for the target integration when it is not already installed | | `--refresh-shared-infra` | Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved) | +| `--integration-options` | Options for the target integration when it is not already installed | If the target integration is not already installed, equivalent to running `uninstall` followed by `install` in a single step. In this mode, `--force` controls whether modified files from the removed integration are deleted. If the target integration is already installed, `switch` only changes the default integration, like `use`; in this mode, `--force` controls whether managed shared templates are overwritten while the default changes. `--integration-options` is rejected for already-installed targets because changing integration options requires reinstalling managed files; run `upgrade --integration-options ...` first, then `use `.