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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-claude-cli
-Version: 0.12.1
+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
@@ -331,6 +331,19 @@ old    keychain  token expired  -       inherit                no      -
 - `error` comes with a reason on stderr, for example `plan lookup failed for work: timeout (via 127.0.0.1:7890, 10.01s)`. `tls_failed` usually means the Python that runs multi-claude has no root certificates (python.org installers ship an `Install Certificates.command`).
 - `list --offline` skips the lookup — no token is read, nothing is sent — and prints the table without the two columns. `list --json` carries the same data in each account's `plan` object (`refresh` tells whether a token was renewed); scripts should use it instead of parsing the table. The lookup adds about a second, at most 15; a renewal that is under way is allowed to finish first (the first Ctrl-C only prints a notice), so that the new login is not lost.
 
+#### Renewal date
+
+Anthropic's interface does not say when a subscription renews, and the date it implies is wrong for an account whose subscription was stopped and started again. Copy the date from the store's subscription page (App Store or Google Play) instead:
+
+```sh
+multi-claude set work --renews 2026-11-10   # the date the store shows
+multi-claude set work --renews off          # forget it
+```
+
+Once any account has a date, `list` adds a `RENEWS` column (also with `--offline`, since nothing is looked up): `11-10 (25d)` is 25 days away, `10-19 (3d!)` three days or less, `10-16 (today!)` today, `10-10 (6d ago)` already passed. A date in another year is written in full, `2027-01-05 (81d)`. Days are counted in your local time zone. When a date has passed — usually because the store renewed the subscription — `list` reminds you on stderr to look up the new date. Accounts without a date show `-`; without any dates the table is unchanged.
+
+`list --json` gives each account `"renews": {"date": "2026-11-10", "days_left": 25}` (`days_left` is negative once the date has passed), or `null`. The date is stored as `renews` in `config.json`; `apply -f FILE` treats it like any other account setting, so an account whose entry in FILE has no `renews` loses its date.
+
 ### Finding a session
 
 Forgot which account or which directory a session was started in? `sessions` lists the sessions of every account and every project directory, newest first; `--cmd` adds the command that resumes each one:
@@ -522,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. |
@@ -529,14 +544,14 @@ It never copies, exports, uploads or backs up a login. One command touches one:
 | `multi-claude restore NAME [--skip-process-check] [--dry-run]` | Undo `migrate-default`: move the account back to `~/.claude` and unregister it. The login is kept. |
 | `multi-claude export NAME FILE` | Write the account's settings, `CLAUDE.md`, agents, commands, skills, output styles and MCP servers to FILE. No logins or sessions. |
 | `multi-claude import FILE NAME [--force] [--dry-run]` | Import such a file into an existing account; conflicts are refused unless `--force` (which backs up first). |
-| `multi-claude add NAME [--proxy P] [--shared [DIR] \| --no-shared] [--adopt] [--shared-exclude ITEM] [--shared-include ITEM] [--config-from OTHER]` | Add an account, adopt an existing directory, or change its options. `--config-from` copies `settings.json` from OTHER once. `--shared DIR` also makes DIR the shared directory for every account (default `~/.claude-shared`). `--shared-exclude` keeps one shared item out of this account; `--shared-include` undoes it. |
-| `multi-claude set NAME [--proxy P] [--shared [DIR] \| --no-shared] [--shared-exclude ITEM] [--shared-include ITEM]` | Change an existing account; same options as `add` without `--adopt`. Returns 1 for an account that is not registered. |
+| `multi-claude add NAME [--proxy P] [--shared [DIR] \| --no-shared] [--adopt] [--shared-exclude ITEM] [--shared-include ITEM] [--renews DATE\|off] [--config-from OTHER]` | Add an account, adopt an existing directory, or change its options. `--config-from` copies `settings.json` from OTHER once. `--renews` records the renewal date (see [Renewal date](#renewal-date)). `--shared DIR` also makes DIR the shared directory for every account (default `~/.claude-shared`). `--shared-exclude` keeps one shared item out of this account; `--shared-include` undoes it. |
+| `multi-claude set NAME [--proxy P] [--shared [DIR] \| --no-shared] [--shared-exclude ITEM] [--shared-include ITEM] [--renews DATE\|off]` | Change an existing account; same options as `add` without `--adopt`. Returns 1 for an account that is not registered. |
 | `multi-claude proxy NAME PORT\|URL\|off\|inherit` | Set an account's proxy. |
 | `multi-claude env (NAME \| --defaults) [K=V ...] [--unset K ...]` | Set or remove extra environment variables. |
 | `multi-claude args (NAME \| --defaults) -- [ARG ...]` | Replace the fixed arguments; `--` with nothing after it clears them. |
 | `multi-claude remove NAME` | Unregister an account and delete its launcher. **The directory and the login are kept.** |
 | `multi-claude apply [-f FILE]` | Converge everything to the configuration (or to `FILE`). |
-| `multi-claude list [--verbose \| --json \| --names] [--no-refresh] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--no-refresh` does not renew expired access tokens (never writes to a login); `--offline` skips the plan lookup (no token read, no network). |
+| `multi-claude list [--verbose \| --json \| --names] [--no-refresh] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--no-refresh` does not renew expired access tokens (never writes to a login); `--offline` skips the plan lookup (no token read, no network). A `RENEWS` column (and a `renews` key in `--json`) shows the renewal dates you recorded. |
 | `multi-claude usage [NAME] [--json]` | Show the last known 5-hour and 7-day usage of each account. |
 | `multi-claude usage --history [NAME] [--days N] [--by day\|model] [--json]` | Token usage per day or model, counted from the session files on this machine (default: 7 days). |
 | `multi-claude doctor [--json] [--verbose]` | Check the configuration, launchers, account directories, shared links, logins and environment. |

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

@@ -304,6 +304,19 @@ old    keychain  token expired  -       inherit                no      -
 - `error` comes with a reason on stderr, for example `plan lookup failed for work: timeout (via 127.0.0.1:7890, 10.01s)`. `tls_failed` usually means the Python that runs multi-claude has no root certificates (python.org installers ship an `Install Certificates.command`).
 - `list --offline` skips the lookup — no token is read, nothing is sent — and prints the table without the two columns. `list --json` carries the same data in each account's `plan` object (`refresh` tells whether a token was renewed); scripts should use it instead of parsing the table. The lookup adds about a second, at most 15; a renewal that is under way is allowed to finish first (the first Ctrl-C only prints a notice), so that the new login is not lost.
 
+#### Renewal date
+
+Anthropic's interface does not say when a subscription renews, and the date it implies is wrong for an account whose subscription was stopped and started again. Copy the date from the store's subscription page (App Store or Google Play) instead:
+
+```sh
+multi-claude set work --renews 2026-11-10   # the date the store shows
+multi-claude set work --renews off          # forget it
+```
+
+Once any account has a date, `list` adds a `RENEWS` column (also with `--offline`, since nothing is looked up): `11-10 (25d)` is 25 days away, `10-19 (3d!)` three days or less, `10-16 (today!)` today, `10-10 (6d ago)` already passed. A date in another year is written in full, `2027-01-05 (81d)`. Days are counted in your local time zone. When a date has passed — usually because the store renewed the subscription — `list` reminds you on stderr to look up the new date. Accounts without a date show `-`; without any dates the table is unchanged.
+
+`list --json` gives each account `"renews": {"date": "2026-11-10", "days_left": 25}` (`days_left` is negative once the date has passed), or `null`. The date is stored as `renews` in `config.json`; `apply -f FILE` treats it like any other account setting, so an account whose entry in FILE has no `renews` loses its date.
+
 ### Finding a session
 
 Forgot which account or which directory a session was started in? `sessions` lists the sessions of every account and every project directory, newest first; `--cmd` adds the command that resumes each one:
@@ -495,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. |
@@ -502,14 +517,14 @@ It never copies, exports, uploads or backs up a login. One command touches one:
 | `multi-claude restore NAME [--skip-process-check] [--dry-run]` | Undo `migrate-default`: move the account back to `~/.claude` and unregister it. The login is kept. |
 | `multi-claude export NAME FILE` | Write the account's settings, `CLAUDE.md`, agents, commands, skills, output styles and MCP servers to FILE. No logins or sessions. |
 | `multi-claude import FILE NAME [--force] [--dry-run]` | Import such a file into an existing account; conflicts are refused unless `--force` (which backs up first). |
-| `multi-claude add NAME [--proxy P] [--shared [DIR] \| --no-shared] [--adopt] [--shared-exclude ITEM] [--shared-include ITEM] [--config-from OTHER]` | Add an account, adopt an existing directory, or change its options. `--config-from` copies `settings.json` from OTHER once. `--shared DIR` also makes DIR the shared directory for every account (default `~/.claude-shared`). `--shared-exclude` keeps one shared item out of this account; `--shared-include` undoes it. |
-| `multi-claude set NAME [--proxy P] [--shared [DIR] \| --no-shared] [--shared-exclude ITEM] [--shared-include ITEM]` | Change an existing account; same options as `add` without `--adopt`. Returns 1 for an account that is not registered. |
+| `multi-claude add NAME [--proxy P] [--shared [DIR] \| --no-shared] [--adopt] [--shared-exclude ITEM] [--shared-include ITEM] [--renews DATE\|off] [--config-from OTHER]` | Add an account, adopt an existing directory, or change its options. `--config-from` copies `settings.json` from OTHER once. `--renews` records the renewal date (see [Renewal date](#renewal-date)). `--shared DIR` also makes DIR the shared directory for every account (default `~/.claude-shared`). `--shared-exclude` keeps one shared item out of this account; `--shared-include` undoes it. |
+| `multi-claude set NAME [--proxy P] [--shared [DIR] \| --no-shared] [--shared-exclude ITEM] [--shared-include ITEM] [--renews DATE\|off]` | Change an existing account; same options as `add` without `--adopt`. Returns 1 for an account that is not registered. |
 | `multi-claude proxy NAME PORT\|URL\|off\|inherit` | Set an account's proxy. |
 | `multi-claude env (NAME \| --defaults) [K=V ...] [--unset K ...]` | Set or remove extra environment variables. |
 | `multi-claude args (NAME \| --defaults) -- [ARG ...]` | Replace the fixed arguments; `--` with nothing after it clears them. |
 | `multi-claude remove NAME` | Unregister an account and delete its launcher. **The directory and the login are kept.** |
 | `multi-claude apply [-f FILE]` | Converge everything to the configuration (or to `FILE`). |
-| `multi-claude list [--verbose \| --json \| --names] [--no-refresh] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--no-refresh` does not renew expired access tokens (never writes to a login); `--offline` skips the plan lookup (no token read, no network). |
+| `multi-claude list [--verbose \| --json \| --names] [--no-refresh] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--no-refresh` does not renew expired access tokens (never writes to a login); `--offline` skips the plan lookup (no token read, no network). A `RENEWS` column (and a `renews` key in `--json`) shows the renewal dates you recorded. |
 | `multi-claude usage [NAME] [--json]` | Show the last known 5-hour and 7-day usage of each account. |
 | `multi-claude usage --history [NAME] [--days N] [--by day\|model] [--json]` | Token usage per day or model, counted from the session files on this machine (default: 7 days). |
 | `multi-claude doctor [--json] [--verbose]` | Check the configuration, launchers, account directories, shared links, logins and environment. |

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

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

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

@@ -15,8 +15,9 @@ import shutil
 import stat
 import subprocess
 import sys
+import textwrap
 import unicodedata
-from datetime import datetime, timedelta, timezone
+from datetime import date, datetime, timedelta, timezone
 from typing import List, NamedTuple, Optional, Tuple
 
 from . import (__version__, accounts, artifacts, bundle, completion, doctor, history, hook, identity, launcher, migrate,
@@ -24,7 +25,7 @@ from . import (__version__, accounts, artifacts, bundle, completion, doctor, his
 from .actions import LOG_PREFIX, error, info, warn
 from .config import (DEFAULT_SHARED_DIR, DEFAULT_SHARED_ITEMS, IDENTITY_DEFAULT, IDENTITY_DIR, Account, Config, ConfigError, RouteRule,
                      is_unshareable, load_config, normalize_proxy, parse_config, validate_env_key, validate_name,
-                     validate_route_path, validate_value, config_path)
+                     validate_renews, validate_route_path, validate_value, config_path)
 from .env import account_env
 from .fsutil import KIND_FILE, KIND_LINK, KIND_MISSING, atomic_write, entry_kind, expand, read_text
 from .lock import LockBusyError, WriteLock
@@ -46,7 +47,7 @@ COMMAND_GROUPS = [
         ("list", "show accounts, logins and usage"),
     ]),
     ("Account settings", [
-        ("set NAME", "change an account: proxy and sharing"),
+        ("set NAME", "change an account: proxy, sharing, renewal date"),
         ("proxy, env, args", "set the proxy, extra variables or fixed arguments of a launcher"),
         ("rename, remove", "rename or unregister an account"),
         ("migrate-default, restore", "turn the existing ~/.claude into an account, or back"),
@@ -74,6 +75,7 @@ _EXAMPLES = [
     ("multi-claude add work --proxy 7901", ""),
     ("multi-claude login work", ""),
     ("multi-claude route ~/work work", ""),
+    ("multi-claude set work --renews 2026-11-10", "record when the plan renews"),
     ("multi-claude add --help", "details of one command"),
 ]
 
@@ -95,12 +97,204 @@ def _help_epilog() -> str:
         for shown, text in items:
             lines.append("  {:<18}{}".format(shown, text))
         lines.append("")
-    lines.append("Examples:")
-    for command, text in _EXAMPLES:
-        lines.append("  {:<36}{}".format(command, text).rstrip())
+    lines.extend(_examples_lines(_EXAMPLES))
     return "\n".join(lines)
 
 
+def _examples_lines(examples: List[Tuple[str, str]]) -> List[str]:
+    """帮助末尾的 Examples: 段。列宽按最长的命令算：固定列宽遇到长命令时说明会紧贴在命令后面，
+    测试按“两个以上空格”切分命令与说明，贴住就切不开（方案 feature-renewal-date §5.1.4）。"""
+    width = max(len(command) for command, _text in examples) + 2
+    lines = ["Examples:"]
+    for command, text in examples:
+        lines.append("  {}{}".format(command.ljust(width), text).rstrip())
+    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"),
+    ("multi-claude set work --proxy off", "start claude-work without a proxy"),
+    ("multi-claude set work --shared", "link the shared items (default {})".format(DEFAULT_SHARED_DIR)),
+    ("multi-claude set work --shared ~/claude-common", "make ~/claude-common the shared directory for every account"),
+    ("multi-claude set work --no-shared", "remove the shared links of this account"),
+    ("multi-claude set work --shared-exclude skills", "do not link skills into this account"),
+    ("multi-claude set work --shared-include skills", "link skills again"),
+    ("multi-claude set work --renews 2026-11-10", "record the renewal date shown by the App Store / Google Play"),
+    ("multi-claude set work --renews off", "forget the renewal date"),
+    ("multi-claude set work --renews 2026-11-10 --dry-run", "show what would change without writing"),
+]
+
+_ADD_EXAMPLES = [
+    ("multi-claude add work", "create account work and its launcher claude-work"),
+    ("multi-claude add work --proxy 7901 --shared", "with a proxy and the shared items"),
+    ("multi-claude add work --no-shared", "keep the account without shared links"),
+    ("multi-claude add work --shared-exclude skills", "share everything except skills"),
+    ("multi-claude add work --shared-include skills", "share skills again"),
+    ("multi-claude add work --renews 2026-11-10", "also record the renewal date"),
+    ("multi-claude add work --shared --adopt", "take over shared links that already exist"),
+    ("multi-claude add work --config-from home", "copy settings.json from account home once"),
+    ("multi-claude add work --dry-run", "show what would be created"),
+]
+
+_LIST_EXAMPLES = [
+    ("multi-claude list", "accounts, plan, usage; RENEWS appears once a renewal date is set"),
+    ("multi-claude list --offline", "no token read, no network (RENEWS still shown)"),
+    ("multi-claude list --no-refresh", "never renew an expired access token"),
+    ("multi-claude list --verbose", "every field and the global settings"),
+    ("multi-claude list --json", 'for scripts; each account has "renews": {"date", "days_left"} or null'),
+    ("multi-claude list --names", "account names only"),
+]
+
+_RENEWS_LEGEND = [
+    "RENEWS: the date you recorded with `multi-claude set NAME --renews YYYY-MM-DD`;",
+    "(25d) days left, (3d!) three days or less, (today!) renews today,",
+    "(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）。
     # 新增子命令时必须同时写进 COMMAND_GROUPS，测试会核对两者一致。
@@ -134,13 +328,18 @@ def build_parser() -> argparse.ArgumentParser:
                        help="do not check whether Claude Code is running (at your own risk)")
     _add_dry_run(p_mig)
 
-    p_add = sub.add_parser("add", description="add an account, adopt an existing directory, or change its options")
+    # 带 epilog 示例的子命令用 RawDescriptionHelpFormatter 保留换行；description 因此不再自动折行，须手动加 \n。
+    p_add = sub.add_parser("add", description="add an account, adopt an existing directory, or change its options",
+                           epilog="\n".join(_examples_lines(_ADD_EXAMPLES)),
+                           formatter_class=argparse.RawDescriptionHelpFormatter)
     _add_account_options(p_add, adopt=True)
     p_add.add_argument("--config-from", metavar="OTHER",
                        help="copy settings.json from account OTHER into this account once")
 
-    p_set = sub.add_parser("set", description="change an existing account: proxy and sharing "
-                                              "(use env, args, rename for the rest)")
+    p_set = sub.add_parser("set", description="change an existing account: proxy, sharing and renewal date\n"
+                                              "(use env, args, rename for the rest)",
+                           epilog="\n".join(_examples_lines(_SET_EXAMPLES)),
+                           formatter_class=argparse.RawDescriptionHelpFormatter)
     _add_account_options(p_set, adopt=False)
 
     p_proxy = sub.add_parser("proxy", description="set the proxy of an account")
@@ -169,8 +368,10 @@ def build_parser() -> argparse.ArgumentParser:
     p_apply.add_argument("-f", "--file", help="use this file as the new configuration")
     _add_write_options(p_apply)
 
-    p_list = sub.add_parser("list", description="show accounts and their status; looks up each account's plan "
-                            "and billing channel from Anthropic unless --offline is given")
+    p_list = sub.add_parser("list", description="show accounts and their status; looks up each account's plan\n"
+                            "and billing channel from Anthropic unless --offline is given",
+                            epilog="\n".join(_examples_lines(_LIST_EXAMPLES) + [""] + _RENEWS_LEGEND),
+                            formatter_class=argparse.RawDescriptionHelpFormatter)
     list_mode = p_list.add_mutually_exclusive_group()
     list_mode.add_argument("--verbose", action="store_true",
                            help="show every field, the global settings and the keychain details")
@@ -313,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
 
 
@@ -341,6 +545,9 @@ def _add_account_options(parser: argparse.ArgumentParser, adopt: bool) -> None:
                              "the link multi-claude made is removed")
     parser.add_argument("--shared-include", action="append", default=[], metavar="ITEM",
                         help="undo --shared-exclude for this item (repeatable)")
+    # 续费日由用户照着 App Store / Google Play 的订阅页手填：服务端接口给不出准确的到期日（方案 feature-renewal-date §1）。
+    parser.add_argument("--renews", metavar="DATE",
+                        help="renewal date of the subscription, YYYY-MM-DD as shown by the store; off to clear it")
     _add_write_options(parser)
 
 
@@ -606,6 +813,8 @@ def dispatch(args: argparse.Namespace) -> int:
             account.shared = True
         elif args.no_shared:
             account.shared = False
+        if args.renews is not None:
+            account.renews = None if args.renews == "off" else _checked_renews(args.renews)
         _apply_shared_exclude(new, account, args.shared_exclude, args.shared_include)
         if getattr(args, "adopt", False):
             # 接管只对开启了共享的账号有意义；关闭状态下工具本来就不管这些软链。
@@ -1178,7 +1387,7 @@ def _hint_next_step(config: Config, name: str) -> None:
 
 def _has_account_option(args: argparse.Namespace) -> bool:
     return bool(args.proxy is not None or args.shared_to is not None or args.no_shared
-                or args.shared_exclude or args.shared_include)
+                or args.shared_exclude or args.shared_include or args.renews is not None)
 
 
 def _looks_like_path(value: str) -> bool:
@@ -1328,6 +1537,13 @@ def _checked_proxy(value: str) -> str:
         raise UsageError(str(exc))
 
 
+def _checked_renews(value: str) -> str:
+    try:
+        return validate_renews(value)
+    except ValueError as exc:
+        raise UsageError(str(exc))
+
+
 def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = False, offline: bool = False,
              refresh_tokens: bool = True) -> int:
     """列出账号。除 --names 与 --offline 外，会读各账号的访问令牌并向服务端查询套餐（方案 feature-live-plan）；
@@ -1346,9 +1562,12 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
     plans = None if offline or not exists else plan.query_all(config, os.environ, datetime.now(timezone.utc),
                                                              allow_refresh=refresh_tokens)
     if as_json:
-        _print_json(_list_data(config, exists, plans))
+        # 只取一次今天：JSON 里的 days_left 与 stderr 的过期提示在跨午夜时也一致。
+        today = _local_today()
+        _print_json(_list_data(config, exists, plans, today))
         if exists:
             _report_plan_problems(plans)
+            _report_renewals(config, today)
             accounts.warn_launch_settings(config, None, note_invalid=True)
         return accounts.EXIT_OK
     if not exists:
@@ -1365,7 +1584,10 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
         return accounts.EXIT_OK
     if "CLAUDE_CODE_CUSTOM_OAUTH_URL" in os.environ:
         warn("CLAUDE_CODE_CUSTOM_OAUTH_URL is set; LOGIN assumes the production service and may be wrong")
-    rows = [("NAME", "IDENTITY", "DIR", "PROXY", "SHARED", "LAUNCHER", "LOGIN") + _plan_header(plans) + ("LINK",)]
+    today = _local_today()
+    renews_shown = _has_renewals(config)
+    rows = [("NAME", "IDENTITY", "DIR", "PROXY", "SHARED", "LAUNCHER", "LOGIN") + _plan_header(plans)
+            + _renews_header(renews_shown) + ("LINK",)]
     details = []
     default_account = None
     for entry in _account_entries(config):
@@ -1373,7 +1595,9 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
             default_account = entry["name"]
         rows.append((entry["name"], entry["identity"], "ok" if entry["dir_exists"] else "missing-dir",
                      entry["proxy"], _shared_cell(entry), entry["launcher"], entry["login"])
-                    + _plan_cells(plans, entry["name"]) + (entry["link"] or "-",))
+                    + _plan_cells(plans, entry["name"])
+                    + _renews_cells(renews_shown, config.find(entry["name"]).renews, today)
+                    + (entry["link"] or "-",))
         if verbose:
             details.append("  {}: keychain service {!r}, credentials file {}".format(
                 entry["name"], entry["keychain_service"], entry["credentials_file"]))
@@ -1385,6 +1609,7 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
     for line in details:
         print(line)
     _report_plan_problems(plans)
+    _report_renewals(config, today)
     accounts.warn_launch_settings(config, None, note_invalid=True)
     return accounts.EXIT_OK
 
@@ -1403,6 +1628,61 @@ def _plan_cells(plans: Optional[dict], name: str) -> tuple:
     return (plan.plan_cell(plans[name]), plan.billing_cell(plans[name]))
 
 
+def _local_today() -> date:
+    """本机时区的今天；续费日按商店页面显示的日期手填，剩余天数也按本地日期算。"""
+    return datetime.now().astimezone().date()
+
+
+def _has_renewals(config: Config) -> bool:
+    """没有任何账号填过续费日时不加 RENEWS 列，表格与改动前完全相同。"""
+    return any(account.renews for account in config.accounts.values())
+
+
+def _renews_header(shown: bool) -> tuple:
+    return ("RENEWS",) if shown else ()
+
+
+def _renews_cells(shown: bool, renews: Optional[str], today: date) -> tuple:
+    return (_renews_cell(renews, today),) if shown else ()
+
+
+def _renews_days(renews: str, today: date) -> int:
+    return (datetime.strptime(renews, "%Y-%m-%d").date() - today).days
+
+
+def _renews_cell(renews: Optional[str], today: date) -> str:
+    """RENEWS 列的一格：同年只写月-日，括号里是剩余天数；3 天内加 !，已过写 ago，提醒去商店页核对后更新。"""
+    if not renews:
+        return "-"
+    day = datetime.strptime(renews, "%Y-%m-%d").date()
+    shown = day.strftime("%m-%d") if day.year == today.year else renews
+    days = (day - today).days
+    if days == 0:
+        return "{} (today!)".format(shown)
+    if days < 0:
+        return "{} ({}d ago)".format(shown, -days)
+    if days <= 3:
+        return "{} ({}d!)".format(shown, days)
+    return "{} ({}d)".format(shown, days)
+
+
+def _renews_dict(renews: Optional[str], today: date) -> Optional[dict]:
+    """--json 的 renews 键：没填为 None；days_left 可为负数（日期已过）。"""
+    if not renews:
+        return None
+    return {"date": renews, "days_left": _renews_days(renews, today)}
+
+
+def _report_renewals(config: Config, today: date) -> None:
+    """续费日已过的账号打一行到 stderr：多半是商店已自动续费、用户还没更新日期。走 stderr 不混进 --json。"""
+    passed = [name for name, account in config.accounts.items()
+              if account.renews and _renews_days(account.renews, today) < 0]
+    if passed:
+        print("{} renewal date has passed for {}: check the store's subscription page, then run "
+              "multi-claude set NAME --renews YYYY-MM-DD (or --renews off)".format(LOG_PREFIX, ", ".join(passed)),
+              file=sys.stderr)
+
+
 def _report_plan_problems(plans: Optional[dict]) -> None:
     """套餐查询与令牌刷新的失败提示，打到 stderr；不影响表格、STATUS 列与退出码。"""
     if plans is None:
@@ -1436,13 +1716,17 @@ def _print_brief_list(config: Config, plans: Optional[dict] = None) -> int:
         # 与完整输出相同：LOGIN 与由它得出的 STATUS 都按正式服务探测，这时可能不准。
         warn("CLAUDE_CODE_CUSTOM_OAUTH_URL is set; LOGIN assumes the production service and may be wrong")
     now = datetime.now(timezone.utc)
-    rows = [("NAME", "LOGIN") + _plan_header(plans) + ("PROXY", "SHARED", "5H", "7D", "LAST USED", "STATUS")]
+    today = _local_today()
+    renews_shown = _has_renewals(config)
+    rows = [("NAME", "LOGIN") + _plan_header(plans) + _renews_header(renews_shown)
+            + ("PROXY", "SHARED", "5H", "7D", "LAST USED", "STATUS")]
     has_problem = False
     for entry in _account_entries(config):
         report = usage.read_account_usage(config, config.find(entry["name"]), now)
         status = _status_cell(entry)
         has_problem = has_problem or status != "ok"
         rows.append((entry["name"], entry["login"]) + _plan_cells(plans, entry["name"])
+                    + _renews_cells(renews_shown, config.find(entry["name"]).renews, today)
                     + (entry["proxy"], _shared_cell(entry),
                        _window_cell(report.five_hour, now), _window_cell(report.seven_day, now),
                        _last_used_cell(entry["last_used"], now), status))
@@ -1451,6 +1735,7 @@ def _print_brief_list(config: Config, plans: Optional[dict] = None) -> int:
     if has_problem:
         print("run multi-claude doctor for details")
     _report_plan_problems(plans)
+    _report_renewals(config, today)
     accounts.warn_launch_settings(config, None, note_invalid=True)
     return accounts.EXIT_OK
 
@@ -1493,9 +1778,11 @@ def _shared_cell(entry: dict) -> str:
     return "yes"
 
 
-def _account_entries(config: Config, with_usage: bool = False, plans: Optional[dict] = None) -> List[dict]:
+def _account_entries(config: Config, with_usage: bool = False, plans: Optional[dict] = None,
+                     today: Optional[date] = None) -> List[dict]:
     """list 的表格与 JSON 共用的每账号数据；表格的列取自这里，保证两种输出口径一致。"""
     now = datetime.now(timezone.utc)
+    today = today or _local_today()
     entries = []
     for name, account in config.accounts.items():
         directory = accounts.account_dir(config, name)
@@ -1515,6 +1802,7 @@ def _account_entries(config: Config, with_usage: bool = False, plans: Optional[d
             "credentials_file": identity.credentials_file(directory),
             # history.jsonl 与会话文件的最大 mtime；只 stat 不读内容（方案 feature-usage-history §5.1.3）
             "last_used": _iso(history.last_used(directory)),
+            "renews": _renews_dict(account.renews, today),
         }
         if with_usage:
             entry["usage"] = usage.report_to_dict(usage.read_account_usage(config, account, now), now)
@@ -1525,7 +1813,7 @@ def _account_entries(config: Config, with_usage: bool = False, plans: Optional[d
     return entries
 
 
-def _list_data(config: Config, exists: bool, plans: Optional[dict] = None) -> dict:
+def _list_data(config: Config, exists: bool, plans: Optional[dict] = None, today: Optional[date] = None) -> dict:
     if not exists:
         return {"schema_version": 1, "configured": False, "accounts": [],
                 "routes": {"default": None, "rules": []}}
@@ -1535,7 +1823,7 @@ def _list_data(config: Config, exists: bool, plans: Optional[dict] = None) -> di
         "root": expand(config.root),
         "bin_dir": expand(config.bin_dir),
         "shared_dir": expand(config.shared_dir) if config.shared_dir else None,
-        "accounts": _account_entries(config, with_usage=True, plans=plans),
+        "accounts": _account_entries(config, with_usage=True, plans=plans, today=today),
         "routes": {"default": config.route_default,
                    "rules": [{"path": rule.path, "account": rule.account, "exists": os.path.isdir(expand(rule.path))}
                              for rule in config.route_rules]},