multi-claude-cli 0.13.0__tar.gz → 0.14.0__tar.gz

{multi_claude_cli-0.13.0 → multi_claude_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-claude-cli
-Version: 0.13.0
+Version: 0.14.0
 Summary: Run several Claude Code accounts side by side: separate CLAUDE_CONFIG_DIR directories, launchers, proxies, environment variables and arguments.
 License: MIT
 Project-URL: Homepage, https://github.com/jakoes-wu/multi-claude
@@ -535,6 +535,8 @@ It never copies, exports, uploads or backs up a login. One command touches one:
 
 ### Commands
 
+Every command's `--help` ends with examples you can copy, covering its options, e.g. `multi-claude route --help`.
+
 | Command | What it does |
 | ---- | ---- |
 | `multi-claude init [--root DIR] [--bin-dir DIR] [--shared-dir DIR] [--shared-items A,B]` | Create or change global settings. |

{multi_claude_cli-0.13.0 → multi_claude_cli-0.14.0}/README.md

@@ -508,6 +508,8 @@ It never copies, exports, uploads or backs up a login. One command touches one:
 
 ### Commands
 
+Every command's `--help` ends with examples you can copy, covering its options, e.g. `multi-claude route --help`.
+
 | Command | What it does |
 | ---- | ---- |
 | `multi-claude init [--root DIR] [--bin-dir DIR] [--shared-dir DIR] [--shared-items A,B]` | Create or change global settings. |

{multi_claude_cli-0.13.0 → multi_claude_cli-0.14.0}/src/multi_claude/__init__.py

@@ -1,3 +1,3 @@
 """multi-claude：管理多个 Claude Code 账号的配置目录、启动命令、代理与启动参数。"""
 
-__version__ = "0.13.0"
+__version__ = "0.14.0"

{multi_claude_cli-0.13.0 → multi_claude_cli-0.14.0}/src/multi_claude/cli.py

@@ -15,6 +15,7 @@ import shutil
 import stat
 import subprocess
 import sys
+import textwrap
 import unicodedata
 from datetime import date, datetime, timedelta, timezone
 from typing import List, NamedTuple, Optional, Tuple
@@ -110,6 +111,16 @@ def _examples_lines(examples: List[Tuple[str, str]]) -> List[str]:
     return lines
 
 
+def _attach_examples(parser: argparse.ArgumentParser, examples: List[Tuple[str, str]]) -> None:
+    """给子命令帮助末尾加 Examples: 段。示例要靠 RawDescriptionHelpFormatter 才能保留列对齐，
+    但它对说明文字也不再折行，所以先把说明按 79 列折好；已手动加过 \\n 的说明是作者自己排过版的，原样保留。
+    argparse 在打印帮助时才读这三个属性，子解析器建好后再设置同样生效（方案 feature-help-examples §3）。"""
+    if "\n" not in (parser.description or ""):
+        parser.description = "\n".join(textwrap.wrap(parser.description or "", 79))
+    parser.epilog = "\n".join(_examples_lines(examples))
+    parser.formatter_class = argparse.RawDescriptionHelpFormatter
+
+
 # 子命令帮助末尾的示例：覆盖该命令的全部选项（公共写选项 --verbose 除外），测试逐条解析核对。
 _SET_EXAMPLES = [
     ("multi-claude set work --proxy 7901", "set the proxy to http://127.0.0.1:7901"),
@@ -151,6 +162,138 @@ _RENEWS_LEGEND = [
     "(6d ago) passed: update it after the store renews.",
 ]
 
+# 其余子命令帮助末尾的示例（方案 feature-help-examples §5.1.2）：合起来覆盖每个选项与固定取值，照抄即可运行；
+# tests/test_help_examples.py 逐条解析、在沙箱里实跑，并核对没有漏掉的选项。add、set、list 的示例在上面单独定义。
+_SUBCOMMAND_EXAMPLES = {
+    "init": [
+        ("multi-claude init --root ~/.cc --bin-dir ~/.local/bin", "where account directories and launchers go"),
+        ("multi-claude init --shared-dir ~/.claude-shared", "directory whose items can be linked into accounts"),
+        ("multi-claude init --shared-items agents,commands,skills,CLAUDE.md", "items to share (this is the default)"),
+        ("multi-claude init --root ~/.cc --dry-run --verbose", "list every planned action without writing"),
+    ],
+    "migrate-default": [
+        ("multi-claude migrate-default --dry-run", "preview; without NAME, usually the login e-mail"),
+        ("multi-claude migrate-default home", "turn ~/.claude into account home, login kept"),
+        ("multi-claude migrate-default home --proxy 7901", "and give it a proxy"),
+        ("multi-claude migrate-default home --copy --keep-backup", "copy instead of rename; keep the original"),
+        ("multi-claude migrate-default home --skip-process-check", "do not check for running Claude Code (risky)"),
+    ],
+    "proxy": [
+        ("multi-claude proxy work 7901", "same as http://127.0.0.1:7901"),
+        ("multi-claude proxy work https://proxy.example.com:8443", "any http(s) URL without user or password"),
+        ("multi-claude proxy work off", "unset the proxy variables in claude-work"),
+        ("multi-claude proxy work inherit --dry-run", "keep the shell's proxy (default); preview only"),
+    ],
+    "env": [
+        ("multi-claude env work MAX_THINKING_TOKENS=8000", "add or change a variable"),
+        ("multi-claude env work --unset MAX_THINKING_TOKENS", "remove it again"),
+        ("multi-claude env --defaults MAX_THINKING_TOKENS=8000", "for every account"),
+        ("multi-claude env work DISABLE_TELEMETRY=1 --dry-run", "preview only"),
+    ],
+    "args": [
+        ("multi-claude args work -- --ide", "claude-work always starts with --ide"),
+        ("multi-claude args --defaults -- --ide", "the same for every account"),
+        ("multi-claude args work --", "clear the fixed arguments of work"),
+        ("multi-claude args work --dry-run -- --ide", "preview only"),
+    ],
+    "remove": [
+        ("multi-claude remove work", "unregister work; directory and login stay"),
+        ("multi-claude remove work --dry-run", "preview only"),
+    ],
+    "apply": [
+        ("multi-claude apply", "rewrite launchers and links to match config.json"),
+        ("multi-claude apply --dry-run --verbose", "list every planned action without writing"),
+        ("multi-claude apply -f accounts.json", "adopt accounts.json as the new configuration"),
+    ],
+    "usage": [
+        ("multi-claude usage", "5-hour and 7-day usage of every account"),
+        ("multi-claude usage work --json", "one account, for scripts"),
+        ("multi-claude usage --history", "tokens per day, last 7 days"),
+        ("multi-claude usage --history work --days 30 --by model", "one account, 30 days, per model"),
+        ("multi-claude usage --history --by day", "per day (the default grouping)"),
+    ],
+    "doctor": [
+        ("multi-claude doctor", "check the setup and suggest fixes"),
+        ("multi-claude doctor --verbose", "also list the checks that passed"),
+        ("multi-claude doctor --json", "for scripts"),
+    ],
+    "route": [
+        ("multi-claude route ~/work work", "claude-auto uses work under ~/work"),
+        ("multi-claude route ~/work --remove", "remove that route"),
+        ("multi-claude route --default home", "use home where no route matches"),
+        ("multi-claude route --no-default", "run plain claude where no route matches"),
+        ("multi-claude route ~/work work --dry-run", "preview only"),
+    ],
+    "rename": [
+        ("multi-claude rename work job", "claude-work becomes claude-job"),
+        ("multi-claude rename work job --dry-run", "preview only"),
+    ],
+    "mcp": [
+        ("multi-claude mcp work list", "the MCP servers of work"),
+        ("multi-claude mcp work add --scope user github -- npx -y @modelcontextprotocol/server-github", "everything after the name goes to `claude mcp`"),
+    ],
+    "login": [
+        ("multi-claude login work", "runs `claude auth login` as work"),
+    ],
+    "which": [
+        ("multi-claude which", "the account claude-auto would use here"),
+        ("multi-claude which ~/work", "... in ~/work"),
+    ],
+    "run": [
+        ("multi-claude run work", "same as claude-work"),
+        ("multi-claude run work -- claude --version", "any command, with the environment of claude-work"),
+        ("multi-claude run -- env", "without a name: the account claude-auto would use here"),
+    ],
+    "path": [
+        ("multi-claude path work", "print the directory of work"),
+    ],
+    "code": [
+        ("multi-claude code work ~/work", "a separate VS Code window for work"),
+        ("multi-claude code work . -- --disable-gpu", "arguments after -- go to VS Code"),
+    ],
+    "restore": [
+        ("multi-claude restore home --dry-run", "preview moving home back to ~/.claude"),
+        ("multi-claude restore home", "undo migrate-default, login kept"),
+        ("multi-claude restore home --skip-process-check", "do not check for running Claude Code (risky)"),
+    ],
+    "export": [
+        ("multi-claude export work ~/work-settings.tar.gz", "settings, CLAUDE.md, agents, skills, MCP; no logins"),
+    ],
+    "import": [
+        ("multi-claude import ~/work-settings.tar.gz home", "into an existing account"),
+        ("multi-claude import ~/work-settings.tar.gz home --dry-run", "preview only"),
+        ("multi-claude import ~/work-settings.tar.gz home --force", "back up and replace items that differ"),
+    ],
+    "completion": [
+        ("multi-claude completion bash > ~/.local/share/bash-completion/completions/multi-claude", "bash completion for your user"),
+        ('multi-claude completion zsh > "${fpath[1]}/_multi-claude"', "zsh: any directory on your fpath"),
+        ("multi-claude completion fish > ~/.config/fish/completions/multi-claude.fish", "fish completion"),
+    ],
+    "statusline": [
+        ("multi-claude statusline install ~/.claude/settings.json", "record fresh usage from the status line"),
+        ("multi-claude statusline uninstall ~/.claude/settings.json --dry-run", "preview restoring the original command"),
+    ],
+    "handoff": [
+        ("! multi-claude handoff home", "inside a Claude session: hand it to home"),
+        ("multi-claude handoff home --from work", "the latest session of work in this directory"),
+        ("multi-claude handoff home --from work --session 3c588340-1219-48df-a231-509866789487", "a given session"),
+        ("multi-claude handoff home --from work --force --dry-run", "preview replacing a different copy"),
+    ],
+    "sessions": [
+        ("multi-claude sessions", "the 30 newest sessions of every account"),
+        ("multi-claude sessions work --limit 10", "one account, 10 sessions"),
+        ("multi-claude sessions --grep importer --cmd", "with the command that resumes each"),
+        ("multi-claude sessions --limit 0 --json", "every session, for scripts"),
+        ("multi-claude conversations --grep importer", "another name for sessions"),
+    ],
+    "artifacts": [
+        ("multi-claude artifacts", "the 30 newest artifacts of every account"),
+        ("multi-claude artifacts work --grep report", "one account, matching text"),
+        ("multi-claude artifacts --path --cmd", "with the source file and the resume command"),
+        ("multi-claude artifacts --limit 0 --json", "every artifact, for scripts"),
+    ],
+}
+
 
 def build_parser() -> argparse.ArgumentParser:
     # 子命令不传 help=，argparse 就不会把它们平铺成一列；改由 epilog 按用途分组列出（方案 feature-clearer-help §5.1.1）。
@@ -371,6 +514,9 @@ def build_parser() -> argparse.ArgumentParser:
                              help="also print, below each artifact, the local file it was published from, marked "
                                   "(missing) when it no longer exists")
     p_artifacts.add_argument("--json", action="store_true", help="print machine-readable JSON")
+    # add、set、list 的示例在 add_parser 时已传入；其余子命令在这里统一挂上（键必须是已定义的子命令名）。
+    for name, examples in _SUBCOMMAND_EXAMPLES.items():
+        _attach_examples(sub.choices[name], examples)
     return parser
 
 

{multi_claude_cli-0.13.0 → multi_claude_cli-0.14.0}/src/multi_claude_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-claude-cli
-Version: 0.13.0
+Version: 0.14.0
 Summary: Run several Claude Code accounts side by side: separate CLAUDE_CONFIG_DIR directories, launchers, proxies, environment variables and arguments.
 License: MIT
 Project-URL: Homepage, https://github.com/jakoes-wu/multi-claude
@@ -535,6 +535,8 @@ It never copies, exports, uploads or backs up a login. One command touches one:
 
 ### Commands
 
+Every command's `--help` ends with examples you can copy, covering its options, e.g. `multi-claude route --help`.
+
 | Command | What it does |
 | ---- | ---- |
 | `multi-claude init [--root DIR] [--bin-dir DIR] [--shared-dir DIR] [--shared-items A,B]` | Create or change global settings. |

{multi_claude_cli-0.13.0 → multi_claude_cli-0.14.0}/src/multi_claude_cli.egg-info/SOURCES.txt

@@ -44,6 +44,7 @@ tests/test_everyday.py
 tests/test_fsutil.py
 tests/test_handoff.py
 tests/test_help.py
+tests/test_help_examples.py
 tests/test_history.py
 tests/test_identity.py
 tests/test_install.py

multi_claude_cli-0.14.0/tests/test_help_examples.py

@@ -0,0 +1,224 @@
+"""方案 feature-help-examples §8：每个子命令的帮助都有示例，示例能解析、能运行、覆盖全部选项。"""
+
+import argparse
+import contextlib
+import io
+import json
+import os
+import re
+import shlex
+import shutil
+import sys
+import unittest
+
+from helpers import CliTestCase, SRC
+
+sys.path.insert(0, SRC)
+
+from multi_claude import cli  # noqa: E402
+
+# 示例里出现这些 shell 运算符时，之后的词交给 shell，不是 multi-claude 的参数。
+SHELL_OPERATORS = (">", ">>", "|")
+
+# E3：这两个命令的 --verbose 是自己的功能；其余命令的 --verbose 来自 _add_write_options，是公共写选项，不要求示例覆盖。
+OWN_VERBOSE = ("list", "doctor")
+
+# E5 跳过的命令及理由（方案 §8.1 第 5 条）；它们的示例仍由 E2 解析核对。
+RUN_SKIPPED = {
+    "list": "looks up plans over the network; its examples are parsed by test_renewal T8",
+    "handoff": "needs a Claude session, or a real session in the source account",
+    "migrate-default": "needs a real ~/.claude and the login e-mail in ~/.claude.json",
+    "restore": "needs an account migrated from ~/.claude",
+    "code": "would start the real VS Code found in PATH; covered by test_vscode with a fake code",
+}
+
+# E5 允许的非零退出码：示例 → (退出码, 原因)。只收沙箱环境造成的失败，退出码 2（参数被拒）一律不允许。
+ALLOWED_EXIT = {}
+
+
+def subparsers():
+    parser = cli.build_parser()
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action.choices
+    raise AssertionError("no subparsers")
+
+
+def help_text(name):
+    out = io.StringIO()
+    with contextlib.redirect_stdout(out):
+        try:
+            cli.build_parser().parse_args([name, "--help"])
+        except SystemExit as exc:
+            if exc.code != 0:
+                raise AssertionError("{} --help exited {}".format(name, exc.code))
+    return out.getvalue()
+
+
+def example_commands(text):
+    """帮助文本 Examples: 段里每行的命令列（与说明之间至少两个空格）。"""
+    if "Examples:" not in text:
+        return []
+    commands = []
+    for line in text.split("Examples:", 1)[1].splitlines()[1:]:
+        if not line.startswith("  "):
+            break
+        commands.append(re.split(r"\s{2,}", line.strip())[0])
+    return commands
+
+
+def example_words(command):
+    """示例命令切成 multi-claude 之后的参数：去掉会话里运行用的 `! `，截掉 shell 运算符之后的部分。"""
+    words = shlex.split(command)
+    if words[:1] == ["!"]:
+        words = words[1:]
+    if words[:1] != ["multi-claude"]:
+        raise AssertionError("example does not start with multi-claude: {}".format(command))
+    words = words[1:]
+    for index, word in enumerate(words):
+        if word in SHELL_OPERATORS:
+            return words[:index]
+    return words
+
+
+def parse_like_main(words):
+    """走 main 在 argparse 之前的同一串步骤（方案 §5.1.3），返回解析结果；--help 示例返回 None。"""
+    parser = cli.build_parser()
+    argv = cli._resolve_command_alias(list(words))
+    problem = cli._unknown_command(parser, argv) or cli._misplaced_account_name(argv)
+    if problem is not None:
+        raise AssertionError(problem)
+    argv, _launch_args = cli._split_args_command(argv)
+    if "--help" in argv or "-h" in argv:
+        return None
+    return parser.parse_args(argv)
+
+
+class HelpExamplesTest(unittest.TestCase):
+    def test_e1_every_subcommand_has_examples(self):
+        names = list(subparsers())
+        self.assertEqual(len(names), 28)
+        for name in names:
+            with self.subTest(command=name):
+                self.assertTrue(example_commands(help_text(name)))
+
+    def test_e2_examples_parse_like_main(self):
+        for name in subparsers():
+            for command in example_commands(help_text(name)):
+                with self.subTest(command=command):
+                    args = parse_like_main(example_words(command))
+                    if args is not None:
+                        # 防止把别的命令的示例贴进这个命令的帮助。
+                        self.assertEqual(args.command, name)
+
+    def test_e3_examples_cover_every_option_and_choice(self):
+        for name, parser in subparsers().items():
+            with self.subTest(command=name):
+                # 按整词比较：子串匹配会让 --shared-exclude 冒充 --shared 已覆盖。
+                used = {word for command in example_commands(help_text(name)) for word in example_words(command)}
+                for action in parser._actions:
+                    if "-h" in action.option_strings:
+                        continue
+                    if action.option_strings == ["--verbose"] and name not in OWN_VERBOSE:
+                        continue
+                    if action.option_strings:
+                        self.assertTrue(set(action.option_strings) & used,
+                                        "{} {} has no example".format(name, action.option_strings))
+                    for choice in action.choices or ():
+                        self.assertIn(choice, used, "{} value {!r} has no example".format(name, choice))
+
+    def test_e4_descriptions_and_example_columns(self):
+        for name, parser in subparsers().items():
+            with self.subTest(command=name):
+                for line in (parser.description or "").splitlines():
+                    self.assertLessEqual(len(line), 80)
+                lines = help_text(name).split("Examples:", 1)[1].splitlines()[1:]
+                lines = lines[:next((i for i, line in enumerate(lines) if not line.startswith("  ")), len(lines))]
+                # 说明列对齐、且与最长的命令至少隔两个空格；只看拆分结果查不出“只隔一个空格”。
+                widest = max(len(re.split(r"\s{2,}", line.strip())[0]) for line in lines)
+                starts = {len(line) - len(re.split(r"\s{2,}", line.strip())[-1]) for line in lines
+                          if re.search(r"\S\s{2,}\S", line)}
+                self.assertEqual(len(starts), 1, lines)
+                self.assertGreaterEqual(starts.pop(), 2 + widest + 2, lines)
+
+    def test_e6_existing_help_untouched(self):
+        # add、set、list 与主帮助的示例在本方案之前就有，统一挂示例的循环不得改动它们。
+        self.assertFalse({"add", "set", "list"} & set(cli._SUBCOMMAND_EXAMPLES))
+        parsers = subparsers()
+        expected = {
+            "add": "\n".join(cli._examples_lines(cli._ADD_EXAMPLES)),
+            "set": "\n".join(cli._examples_lines(cli._SET_EXAMPLES)),
+            "list": "\n".join(cli._examples_lines(cli._LIST_EXAMPLES) + [""] + cli._RENEWS_LEGEND),
+        }
+        for name, epilog in expected.items():
+            with self.subTest(command=name):
+                self.assertEqual(parsers[name].epilog, epilog)
+                self.assertIs(parsers[name].formatter_class, argparse.RawDescriptionHelpFormatter)
+        self.assertEqual(parsers["add"].description,
+                         "add an account, adopt an existing directory, or change its options")
+        self.assertEqual(parsers["set"].description, "change an existing account: proxy, sharing and renewal date\n"
+                                                     "(use env, args, rename for the rest)")
+        self.assertEqual(parsers["list"].description, "show accounts and their status; looks up each account's plan\n"
+                                                      "and billing channel from Anthropic unless --offline is given")
+        main = cli.build_parser()
+        self.assertEqual(main.epilog, cli._help_epilog())
+        self.assertEqual(main.description,
+                         "Manage multiple Claude Code accounts: separate CLAUDE_CONFIG_DIR directories,\n"
+                         "per-account launchers, proxies, environment variables and arguments.")
+        self.assertIs(main.formatter_class, argparse.RawDescriptionHelpFormatter)
+
+
+class HelpExamplesRunTest(CliTestCase):
+    """E5（方案 §8.1）：在沙箱里以子进程真正运行示例，确认照抄能用，不只是能解析。"""
+
+    def prepare(self, name):
+        self.ok("add", "work")
+        self.ok("add", "home")
+        os.makedirs(os.path.join(self.home, "work"))
+        if name == "run":
+            # 不给账号名的 `run -- env` 要靠路由或默认账号选账号，否则以用法错误退出。
+            self.ok("route", "--default", "home")
+        elif name == "import":
+            # 只在 import 沙箱预先导出：export 沙箱若也有这个文件，export 示例会因目标已存在而失败。
+            self.ok("export", "work", os.path.join(self.home, "work-settings.tar.gz"))
+        elif name == "apply":
+            shutil.copy(os.path.join(self.state, "config.json"), os.path.join(self.home, "accounts.json"))
+        elif name == "add":
+            # add work --config-from home 要从 home 复制 settings.json。
+            self.write(os.path.join(self.root, "home", "settings.json"), "{}")
+        elif name == "statusline":
+            # install 要在 PATH 里找到 multi-claude；install 与 uninstall 都要读一份带 command 类型 statusLine 的设置文件。
+            fake = self.write(os.path.join(self.fakebin, "multi-claude"), "#!/bin/sh\nexit 0\n")
+            os.chmod(fake, 0o755)
+            self.write(os.path.join(self.home, ".claude", "settings.json"),
+                       json.dumps({"statusLine": {"type": "command", "command": "echo usage"}}))
+
+    def run_example(self, command):
+        # shlex 不展开 ~，multi-claude 的部分命令也不展开，这里按 shell 的规则展开到沙箱的 home。
+        words = [self.home + word[1:] if word == "~" or word.startswith("~/") else word
+                 for word in example_words(command)]
+        return self.run_cli(*words, cwd=self.home)
+
+    def check_examples_run(self, name):
+        commands = example_commands(help_text(name))
+        if name != "statusline":
+            # 先跑预览：rename / remove 真改之后，同命令的 --dry-run 示例会找不到账号。
+            # statusline 例外，按顺序跑，uninstall 的预览才是 install 之后的还原。
+            commands = [c for c in commands if "--dry-run" in c] + [c for c in commands if "--dry-run" not in c]
+        self.prepare(name)
+        for command in commands:
+            with self.subTest(command=command):
+                result = self.run_example(command)
+                expected = ALLOWED_EXIT.get(command, (0, ""))[0]
+                self.assertNotEqual(result.code, 2, result)
+                self.assertEqual(result.code, expected, result)
+
+
+# 每个子命令一个测试方法，各自一个新沙箱：前一个命令的示例不会改掉后一个命令依赖的账号与文件。
+for _name in subparsers():
+    if _name not in RUN_SKIPPED:
+        setattr(HelpExamplesRunTest, "test_e5_" + _name.replace("-", "_"),
+                lambda self, name=_name: self.check_examples_run(name))
+
+if __name__ == "__main__":
+    unittest.main()