agent-toggle 0.12.0__tar.gz → 0.13.0__tar.gz

{agent_toggle-0.12.0 → agent_toggle-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-toggle
-Version: 0.12.0
+Version: 0.13.0
 Summary: Temporarily disable / re-enable AI-agent skills, agents, commands, rules, plugins and MCP servers across harnesses (Claude Code, Codex, Grok, OpenCode, OpenClaw, Copilot, Vibe, Devin, Antigravity)
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/weskao/agent-toggle
@@ -59,10 +59,11 @@ language, update check and Telegram notifications. It also runs tools such as `d
 
 ![agent-toggle config: the settings menu](https://raw.githubusercontent.com/weskao/agent-toggle/main/docs/images/config-menu.jpeg)
 
-**`/agent-toggle` inside Claude Code**: the same picker as a pane, for turning skills, MCP
-servers, plugins and mods on or off without leaving the session ([Claude Code pane mod](#claude-code-pane-mod)).
+**`/agent-toggle` inside Claude Code**: the same picker as a pane. Search, then turn skills, MCP
+servers, plugins and mods on or off without leaving the session; each toggle applies at once and
+queues the matching reload ([Claude Code pane mod](#claude-code-pane-mod)).
 
-![/agent-toggle: the picker as a Claude Code pane](https://raw.githubusercontent.com/weskao/agent-toggle/main/docs/images/claude-pane-mod.jpeg)
+![/agent-toggle: searching and toggling resources in the Claude Code pane](https://raw.githubusercontent.com/weskao/agent-toggle/main/docs/images/claude-mods-demo.gif)
 
 ## Why
 
@@ -146,17 +147,12 @@ tool itself stays in one place.
 **Optional: Telegram alerts for CI** (for maintainers of a fork or clone). The
 Telegram support comes from [telegram-kit](https://pypi.org/project/telegram-kit/)
 (itself stdlib-only), which every install includes, so a reinstall or upgrade keeps
-your settings. Run the setup once; see [CI notifications](#ci-notifications):
-
-```sh
-agent-toggle config                          # settings menu: bot token + chat id live under Notifications
-agent-toggle config sync-ci                  # set the two GitHub repository secrets
-```
+your settings. The settings menu hides its Telegram rows for now; set up the alerts as in
+[CI notifications](#ci-notifications).
 
 The old `agent-toggle[telegram]` extra still resolves and is now a no-op. If
 telegram-kit is missing from a broken install, `config test` and `config sync-ci`
-exit `4`, bare `config` still opens, and the Telegram rows read
-`telegram-kit missing: reinstall agent-toggle`.
+exit `4`.
 
 **Optional: the Claude Code pane mod** (the picker as a pane inside Claude Code, claude harness
 only). It is not part of the PyPI package; with `agent-toggle` already on `PATH` from one of the
@@ -172,16 +168,27 @@ See [Claude Code pane mod](#claude-code-pane-mod).
 
 ## Shell completion
 
-Each release publishes static completion files for bash, zsh and fish as the
-`completions` artifact of its Release workflow run. They are generated from the
-CLI parser; to build them from a checkout:
+`agent-toggle completion <shell>` prints a static completion script, built from the CLI
+parser, for bash, zsh, fish or PowerShell. Save it once where your shell loads it, and
+run the same line again after an upgrade so new commands complete:
 
 ```sh
-python3 tools/gen_completions.py completions   # agent-toggle.bash, _agent-toggle (zsh), agent-toggle.fish
+# zsh: needs fpath=(~/.zfunc $fpath) before compinit in ~/.zshrc
+mkdir -p ~/.zfunc && agent-toggle completion zsh > ~/.zfunc/_agent-toggle
+# bash: loaded on demand by the bash-completion package
+mkdir -p ~/.local/share/bash-completion/completions && agent-toggle completion bash > ~/.local/share/bash-completion/completions/agent-toggle
+# fish
+agent-toggle completion fish > ~/.config/fish/completions/agent-toggle.fish
+```
+
+```powershell
+# PowerShell: save the script, then load it from your profile
+agent-toggle completion powershell > "$HOME\agent-toggle.ps1"; Add-Content $PROFILE '. "$HOME\agent-toggle.ps1"'
 ```
 
-Source `agent-toggle.bash` from `~/.bashrc`, put `_agent-toggle` on your zsh
-`fpath`, or copy `agent-toggle.fish` to `~/.config/fish/completions/`.
+Without the bash-completion package, add `source <file>` to `~/.bashrc` instead.
+`python3 tools/gen_completions.py completions` writes all four files from a checkout; the
+Release workflow uploads them as its `completions` artifact.
 
 ## Usage
 
@@ -258,7 +265,9 @@ unshared).
 `--dry-run` (`disable` / `enable` / `enable --all` / `undo` / `profile apply` /
 `install-shims` / `ui`) computes the plan --
 moves, companions, backups, MCP edits, warnings -- and writes nothing: no state,
-log, lock or backup, and no chmod; it never shells out to `claude`. `disable` /
+log, lock or backup, and no chmod; it never shells out to `claude`, except one
+read-only `claude plugin list --json` (up to 30 s) when a killed run left a plugin
+op pending and has to be settled. `disable` /
 `enable` result rows have action `would-disable` / `would-enable`; every plan
 row has status `planned`. Read-only commands (`list`, `status`, `cost`) also
 change nothing on disk -- `status` warns about a `state.json` or
@@ -426,8 +435,7 @@ end of input, `q` or an empty line exits `0`
 | General | Check for updates, Color, Logo, Language, Default harness |
 | Harnesses | one On/Off per harness, with `found ~/.x` or `not on this machine` |
 | Picker | default sort, harness filter, type filter |
-| Notifications | Telegram bot token (masked, last 4 characters shown), Telegram chat ID |
-| Tools | Health check (`doctor`; then asks y/n per fix it can run), Install shims, Undo last change (asks y/n), Send test message, Sync CI secrets (asks y/n); their output shows in an overlay |
+| Tools | Health check (`doctor`; then asks y/n per fix it can run), Install shims, Undo last change (asks y/n); their output shows in an overlay |
 
 Keys: `↑` `↓` move (wraps, skips headings), `←` `→` cycle a value, `Enter` / `Space` change or run
 the row, `r` reset the row, `R` reset everything (asks y/n), `q` / `Esc` / `Ctrl-C` quit. In an
@@ -566,7 +574,7 @@ rather than guessing.
 
 OpenCode may read skills from another harness's directory through
 `opencode.json` → `skills.paths` (absolute, `~`, `$HOME/...`
-and `${HOME}/...` entries; read from `opencode.json`, else `opencode.jsonc`;
+and `${HOME}/...` entries; read from `opencode.json` and `opencode.jsonc` (OpenCode loads both and merges them);
 relative entries are skipped, since OpenCode resolves them against the session
 directory). OpenCode also always scans `~/.claude/skills` and `~/.agents/skills`,
 so claude's skills count as shared with it. Such a directory is **one** item, filed under
@@ -574,6 +582,11 @@ its owner (the harness whose home really holds it): it is
 parked once, tracked once, and every row reports `shared_with`, the other
 harnesses it also affects. `status` prints `shared dir with: ...`.
 
+Disabling an OpenCode skill while a same-named copy sits in another scanned dir warns
+that OpenCode still loads that copy (stderr, and `warnings` in `--json`). Two copies of
+one name under one owner share one record, so a second `disable` is refused with
+`another copy is already parked at <path> -- enable it first`.
+
 If the live directory carries `.synced-from-*` markers, a sync job may
 re-create what you parked; `status` and `disable` warn about it. Park in the
 source harness instead. The warning is printed once per real directory, naming
@@ -873,10 +886,11 @@ a warning and a `recovered` log row (which `undo` does not reverse). `status` an
 `doctor` report it, with `agent-toggle enable ...` when the item ends up
 disabled. The one case left to you is a cross-filesystem move killed between its
 two renames: both copies are complete, and the report names the `diff -r` to
-check and the `rm -rf` that keeps either one. MCP and plugin items are saved
-per item (when the next one starts), without a `pending` record (a project `.mcp.json`
-edit has one): a kill inside that window
-leaves the change unrecorded (an MCP server's backup stays in `mcp-backups/`).
+check and the `rm -rf` that keeps either one. MCP servers (user-scope json,
+claude-json, toml, project `.mcp.json`) and claude plugins have a `pending` record
+too (a plugin is settled from a live `claude plugin list --json`); only a
+`claude.ai` connector toggle is saved per item (when the next one starts), and a
+kill inside that window leaves its change unrecorded.
 A killed run also leaves its `lock`; the next run's error says so.
 
 Each `log.jsonl` row is `{ts, harness, type, name, action, result, batch,
@@ -1027,21 +1041,24 @@ it on macOS, Linux and Windows.
 
 ## CI notifications
 
-`.github/workflows/ci.yml` can send a Telegram message when the test matrix fails on a
-push (a lint-only failure does not page). Alerts never fire for pull requests or green
-runs. The message names the repository, branch, 7-character commit and a link to the run.
+CI and the Release workflow can send a Telegram message when they fail: `ci.yml` when the
+test matrix fails on a push (a lint-only failure does not page), `release.yml` when the
+build, PyPI publish or post-publish smoke test fails. Alerts never fire for pull requests or
+green runs. Both call `.github/workflows/notify-telegram.yml`, and the message names the
+failure, repository, tag or branch, 7-character commit and a link to the run.
 
-Set it up once, with the `telegram` extra installed (see [Install](#install)):
+The [settings menu](#settings--config-menu) hides its Telegram rows (bot token, chat ID,
+Send test message, Sync CI secrets) for now; `SHOW_TELEGRAM` in `agent_toggle/ui/config_menu.py`
+brings them back. `config test` and `config sync-ci` still work: they read a bot token and
+chat ID saved earlier, else `TG_BOT_TOKEN` / `TG_CHAT_ID` from the environment. Without
+either, set the secrets by hand (below).
 
 ```sh
-agent-toggle config            # settings menu: Notifications has the bot token (hidden) and chat id
 agent-toggle config test       # send one test message
 agent-toggle config sync-ci    # set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID on the repo
 ```
 
-In the [settings menu](#settings--config-menu) an inline field commits on `Enter`, cancels on
-`Esc`, and clears on `-` then `Enter`; the Tools group also has Send test message and Sync CI
-secrets (the same as `config test` / `config sync-ci`). The bot token
+When the rows are shown, the bot token
 is kept only in the OS credential store (macOS Keychain, Linux Secret Service, Windows DPAPI)
 through telegram-kit, never in a file or on a command line, and is shown masked. With no
 credential store it refuses to store the token; set `TG_BOT_TOKEN` in the environment instead
@@ -1057,6 +1074,12 @@ gh secret set TELEGRAM_BOT_TOKEN
 gh secret set TELEGRAM_CHAT_ID
 ```
 
+To check the repository secrets themselves, send a test message through the same workflow:
+
+```sh
+gh workflow run notify-telegram.yml    # optional: -f title="..."
+```
+
 With either secret unset (a fork, or a clone you have not configured) the notify job
 prints a `::notice::` and exits 0, so it never adds a second red X.
 

{agent_toggle-0.12.0 → agent_toggle-0.13.0}/README.md

@@ -26,10 +26,11 @@ language, update check and Telegram notifications. It also runs tools such as `d
 
 ![agent-toggle config: the settings menu](https://raw.githubusercontent.com/weskao/agent-toggle/main/docs/images/config-menu.jpeg)
 
-**`/agent-toggle` inside Claude Code**: the same picker as a pane, for turning skills, MCP
-servers, plugins and mods on or off without leaving the session ([Claude Code pane mod](#claude-code-pane-mod)).
+**`/agent-toggle` inside Claude Code**: the same picker as a pane. Search, then turn skills, MCP
+servers, plugins and mods on or off without leaving the session; each toggle applies at once and
+queues the matching reload ([Claude Code pane mod](#claude-code-pane-mod)).
 
-![/agent-toggle: the picker as a Claude Code pane](https://raw.githubusercontent.com/weskao/agent-toggle/main/docs/images/claude-pane-mod.jpeg)
+![/agent-toggle: searching and toggling resources in the Claude Code pane](https://raw.githubusercontent.com/weskao/agent-toggle/main/docs/images/claude-mods-demo.gif)
 
 ## Why
 
@@ -113,17 +114,12 @@ tool itself stays in one place.
 **Optional: Telegram alerts for CI** (for maintainers of a fork or clone). The
 Telegram support comes from [telegram-kit](https://pypi.org/project/telegram-kit/)
 (itself stdlib-only), which every install includes, so a reinstall or upgrade keeps
-your settings. Run the setup once; see [CI notifications](#ci-notifications):
-
-```sh
-agent-toggle config                          # settings menu: bot token + chat id live under Notifications
-agent-toggle config sync-ci                  # set the two GitHub repository secrets
-```
+your settings. The settings menu hides its Telegram rows for now; set up the alerts as in
+[CI notifications](#ci-notifications).
 
 The old `agent-toggle[telegram]` extra still resolves and is now a no-op. If
 telegram-kit is missing from a broken install, `config test` and `config sync-ci`
-exit `4`, bare `config` still opens, and the Telegram rows read
-`telegram-kit missing: reinstall agent-toggle`.
+exit `4`.
 
 **Optional: the Claude Code pane mod** (the picker as a pane inside Claude Code, claude harness
 only). It is not part of the PyPI package; with `agent-toggle` already on `PATH` from one of the
@@ -139,16 +135,27 @@ See [Claude Code pane mod](#claude-code-pane-mod).
 
 ## Shell completion
 
-Each release publishes static completion files for bash, zsh and fish as the
-`completions` artifact of its Release workflow run. They are generated from the
-CLI parser; to build them from a checkout:
+`agent-toggle completion <shell>` prints a static completion script, built from the CLI
+parser, for bash, zsh, fish or PowerShell. Save it once where your shell loads it, and
+run the same line again after an upgrade so new commands complete:
 
 ```sh
-python3 tools/gen_completions.py completions   # agent-toggle.bash, _agent-toggle (zsh), agent-toggle.fish
+# zsh: needs fpath=(~/.zfunc $fpath) before compinit in ~/.zshrc
+mkdir -p ~/.zfunc && agent-toggle completion zsh > ~/.zfunc/_agent-toggle
+# bash: loaded on demand by the bash-completion package
+mkdir -p ~/.local/share/bash-completion/completions && agent-toggle completion bash > ~/.local/share/bash-completion/completions/agent-toggle
+# fish
+agent-toggle completion fish > ~/.config/fish/completions/agent-toggle.fish
+```
+
+```powershell
+# PowerShell: save the script, then load it from your profile
+agent-toggle completion powershell > "$HOME\agent-toggle.ps1"; Add-Content $PROFILE '. "$HOME\agent-toggle.ps1"'
 ```
 
-Source `agent-toggle.bash` from `~/.bashrc`, put `_agent-toggle` on your zsh
-`fpath`, or copy `agent-toggle.fish` to `~/.config/fish/completions/`.
+Without the bash-completion package, add `source <file>` to `~/.bashrc` instead.
+`python3 tools/gen_completions.py completions` writes all four files from a checkout; the
+Release workflow uploads them as its `completions` artifact.
 
 ## Usage
 
@@ -225,7 +232,9 @@ unshared).
 `--dry-run` (`disable` / `enable` / `enable --all` / `undo` / `profile apply` /
 `install-shims` / `ui`) computes the plan --
 moves, companions, backups, MCP edits, warnings -- and writes nothing: no state,
-log, lock or backup, and no chmod; it never shells out to `claude`. `disable` /
+log, lock or backup, and no chmod; it never shells out to `claude`, except one
+read-only `claude plugin list --json` (up to 30 s) when a killed run left a plugin
+op pending and has to be settled. `disable` /
 `enable` result rows have action `would-disable` / `would-enable`; every plan
 row has status `planned`. Read-only commands (`list`, `status`, `cost`) also
 change nothing on disk -- `status` warns about a `state.json` or
@@ -393,8 +402,7 @@ end of input, `q` or an empty line exits `0`
 | General | Check for updates, Color, Logo, Language, Default harness |
 | Harnesses | one On/Off per harness, with `found ~/.x` or `not on this machine` |
 | Picker | default sort, harness filter, type filter |
-| Notifications | Telegram bot token (masked, last 4 characters shown), Telegram chat ID |
-| Tools | Health check (`doctor`; then asks y/n per fix it can run), Install shims, Undo last change (asks y/n), Send test message, Sync CI secrets (asks y/n); their output shows in an overlay |
+| Tools | Health check (`doctor`; then asks y/n per fix it can run), Install shims, Undo last change (asks y/n); their output shows in an overlay |
 
 Keys: `↑` `↓` move (wraps, skips headings), `←` `→` cycle a value, `Enter` / `Space` change or run
 the row, `r` reset the row, `R` reset everything (asks y/n), `q` / `Esc` / `Ctrl-C` quit. In an
@@ -533,7 +541,7 @@ rather than guessing.
 
 OpenCode may read skills from another harness's directory through
 `opencode.json` → `skills.paths` (absolute, `~`, `$HOME/...`
-and `${HOME}/...` entries; read from `opencode.json`, else `opencode.jsonc`;
+and `${HOME}/...` entries; read from `opencode.json` and `opencode.jsonc` (OpenCode loads both and merges them);
 relative entries are skipped, since OpenCode resolves them against the session
 directory). OpenCode also always scans `~/.claude/skills` and `~/.agents/skills`,
 so claude's skills count as shared with it. Such a directory is **one** item, filed under
@@ -541,6 +549,11 @@ its owner (the harness whose home really holds it): it is
 parked once, tracked once, and every row reports `shared_with`, the other
 harnesses it also affects. `status` prints `shared dir with: ...`.
 
+Disabling an OpenCode skill while a same-named copy sits in another scanned dir warns
+that OpenCode still loads that copy (stderr, and `warnings` in `--json`). Two copies of
+one name under one owner share one record, so a second `disable` is refused with
+`another copy is already parked at <path> -- enable it first`.
+
 If the live directory carries `.synced-from-*` markers, a sync job may
 re-create what you parked; `status` and `disable` warn about it. Park in the
 source harness instead. The warning is printed once per real directory, naming
@@ -840,10 +853,11 @@ a warning and a `recovered` log row (which `undo` does not reverse). `status` an
 `doctor` report it, with `agent-toggle enable ...` when the item ends up
 disabled. The one case left to you is a cross-filesystem move killed between its
 two renames: both copies are complete, and the report names the `diff -r` to
-check and the `rm -rf` that keeps either one. MCP and plugin items are saved
-per item (when the next one starts), without a `pending` record (a project `.mcp.json`
-edit has one): a kill inside that window
-leaves the change unrecorded (an MCP server's backup stays in `mcp-backups/`).
+check and the `rm -rf` that keeps either one. MCP servers (user-scope json,
+claude-json, toml, project `.mcp.json`) and claude plugins have a `pending` record
+too (a plugin is settled from a live `claude plugin list --json`); only a
+`claude.ai` connector toggle is saved per item (when the next one starts), and a
+kill inside that window leaves its change unrecorded.
 A killed run also leaves its `lock`; the next run's error says so.
 
 Each `log.jsonl` row is `{ts, harness, type, name, action, result, batch,
@@ -994,21 +1008,24 @@ it on macOS, Linux and Windows.
 
 ## CI notifications
 
-`.github/workflows/ci.yml` can send a Telegram message when the test matrix fails on a
-push (a lint-only failure does not page). Alerts never fire for pull requests or green
-runs. The message names the repository, branch, 7-character commit and a link to the run.
+CI and the Release workflow can send a Telegram message when they fail: `ci.yml` when the
+test matrix fails on a push (a lint-only failure does not page), `release.yml` when the
+build, PyPI publish or post-publish smoke test fails. Alerts never fire for pull requests or
+green runs. Both call `.github/workflows/notify-telegram.yml`, and the message names the
+failure, repository, tag or branch, 7-character commit and a link to the run.
 
-Set it up once, with the `telegram` extra installed (see [Install](#install)):
+The [settings menu](#settings--config-menu) hides its Telegram rows (bot token, chat ID,
+Send test message, Sync CI secrets) for now; `SHOW_TELEGRAM` in `agent_toggle/ui/config_menu.py`
+brings them back. `config test` and `config sync-ci` still work: they read a bot token and
+chat ID saved earlier, else `TG_BOT_TOKEN` / `TG_CHAT_ID` from the environment. Without
+either, set the secrets by hand (below).
 
 ```sh
-agent-toggle config            # settings menu: Notifications has the bot token (hidden) and chat id
 agent-toggle config test       # send one test message
 agent-toggle config sync-ci    # set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID on the repo
 ```
 
-In the [settings menu](#settings--config-menu) an inline field commits on `Enter`, cancels on
-`Esc`, and clears on `-` then `Enter`; the Tools group also has Send test message and Sync CI
-secrets (the same as `config test` / `config sync-ci`). The bot token
+When the rows are shown, the bot token
 is kept only in the OS credential store (macOS Keychain, Linux Secret Service, Windows DPAPI)
 through telegram-kit, never in a file or on a command line, and is shown masked. With no
 credential store it refuses to store the token; set `TG_BOT_TOKEN` in the environment instead
@@ -1024,6 +1041,12 @@ gh secret set TELEGRAM_BOT_TOKEN
 gh secret set TELEGRAM_CHAT_ID
 ```
 
+To check the repository secrets themselves, send a test message through the same workflow:
+
+```sh
+gh workflow run notify-telegram.yml    # optional: -f title="..."
+```
+
 With either secret unset (a fork, or a clone you have not configured) the notify job
 prints a `::notice::` and exits 0, so it never adds a second red X.
 

{agent_toggle-0.12.0 → agent_toggle-0.13.0}/agent_toggle/__init__.py

@@ -1,3 +1,3 @@
 """agent-toggle: temporarily disable / re-enable AI-agent resources."""
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"

{agent_toggle-0.12.0 → agent_toggle-0.13.0}/agent_toggle/backends/mcp_json.py

@@ -134,7 +134,7 @@ def read_project_mcp(file: Path) -> tuple[str, dict]:
     try:
         if file.stat().st_size > MAX_PROJECT_MCP:
             raise ProjectMcpError(f"{file} is larger than {MAX_PROJECT_MCP >> 20} MiB")
-        text = file.read_bytes().decode("utf-8")      # bytes: CRLF must survive
+        text = fs.read_utf8(file)                     # bytes: CRLF must survive
     except FileNotFoundError:
         raise ProjectMcpError(f"{file} not found") from None
     except (OSError, UnicodeDecodeError) as e:

{agent_toggle-0.12.0 → agent_toggle-0.13.0}/agent_toggle/backends/plugin_cli.py

@@ -59,8 +59,8 @@ def run_cli(binary: str | None, args: list[str], cwd: str | None = None,
         return False, "CLI not found on PATH"
     limit = _timeout(timeout)
     try:
-        p = runner([binary, *args], capture_output=True, text=True,
-                   timeout=limit, cwd=cwd)
+        p = runner([binary, *args], capture_output=True, text=True, encoding="utf-8",
+                   errors="replace", timeout=limit, cwd=cwd)     # Windows: not cp1252
     except subprocess.TimeoutExpired:
         return False, f"CLI timed out after {limit:g}s (raise it with {TIMEOUT_ENV}=<seconds>)"
     except OSError as e:                     # cwd gone, binary unexecutable
@@ -79,7 +79,8 @@ def list_plugins(warn: Callable[[str], None]) -> list[dict]:
     except ValueError:
         data = None
     if not isinstance(data, list):
-        warn("could not read `claude plugin list --json`; plugin rows come from state only")
+        why = f" ({text.splitlines()[-1][:120]})" if not ok and text else ""   # e.g. a timeout
+        warn(f"could not read `claude plugin list --json`{why}; plugin rows come from state only")
         return []
     return [p for p in data if isinstance(p, dict) and isinstance(p.get("id"), str)]
 

{agent_toggle-0.12.0 → agent_toggle-0.13.0}/agent_toggle/cli.py

@@ -51,6 +51,7 @@ from pathlib import Path
 
 from . import (
     __version__,
+    completions,
     config,
     cost,
     doctor,
@@ -558,7 +559,7 @@ def _stale_ignore_lines(h, args: argparse.Namespace, out: Result) -> None:
 
 
 COMMANDS = ("ui", "pick", "status", "list", "cost", "migrate", "disable", "enable",
-            "install-shims", "profile", "undo", "doctor", "config", "update")
+            "install-shims", "profile", "undo", "doctor", "config", "update", "completion")
 _GLOBAL_FLAGS = ("--json", "-v", "--verbose")
 
 
@@ -701,6 +702,9 @@ def build_parser() -> argparse.ArgumentParser:
                     help="test: send one message | sync-ci: set the GitHub repo secrets")
     cf.add_argument("--repo", metavar="OWNER/REPO", help="sync-ci: repository (default: this one)")
     cf.add_argument("--dry-run", action="store_true", help="sync-ci: show the plan; set nothing")
+    cm = sub.add_parser("completion", parents=[common],
+                        help="print the shell completion script")
+    cm.add_argument("shell", choices=list(completions.SHELLS))
     up2 = sub.add_parser("undo", parents=[common], help="reverse the last logged batch")
     up2.add_argument("--dry-run", action="store_true", help="show the plan; change nothing")
     for name, verb in (("disable", "park"), ("enable", "restore")):
@@ -730,7 +734,8 @@ def main(argv: list[str] | None = None) -> int:
     i18n.set_language(language)
     color = scan_color(argv, color)     # --color > env > setting > auto
     i = _command_index(argv)
-    started = None if argv[i:i + 1] == ["update"] else update_prompt.start()   # `update` is the check
+    # `update` is the check; `completion` may run on every shell start (eval "$(...)")
+    started = None if argv[i:i + 1] in (["update"], ["completion"]) else update_prompt.start()
     try:
         return _main(argv, color)
     except KeyboardInterrupt:
@@ -802,6 +807,17 @@ def _main(argv: list[str], color: str) -> int:
             update_prompt.cmd_update(out)
         elif cmd == "config":
             config.cmd_config(args, out)
+        elif cmd == "completion":
+            if out.json_mode:
+                die("completion prints a shell script; --json is not supported", 2)
+            text = completions.script(args.shell, build_parser())
+            buf = getattr(sys.stdout, "buffer", None)
+            if buf is None:                 # a StringIO: no newline translation to dodge
+                print(text, end="")
+            else:                           # bytes: Windows text stdout would write \r\n,
+                sys.stdout.flush()          # which bash rejects
+                buf.write(text.encode("utf-8"))
+                buf.flush()
         elif cmd == "undo":
             undo.cmd_undo(args.dry_run, args.harness, out)
         elif cmd == "enable" and args.all: