compshare-cli 0.3.3__tar.gz → 0.3.5__tar.gz

compshare_cli-0.3.5/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: compshare-cli
+Version: 0.3.5
+Summary: Command-line client for CompShare GPU compute
+Author: CompShare
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/BennielAllan/compshare-cli
+Project-URL: Repository, https://github.com/BennielAllan/compshare-cli
+Project-URL: Changelog, https://github.com/BennielAllan/compshare-cli/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/BennielAllan/compshare-cli/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9,>=8.1
+Requires-Dist: pexpect<5,>=4.9; platform_system != "Windows"
+Requires-Dist: rich<15,>=13
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: ucloud-sdk-python3<0.12,>=0.11.103
+Requires-Dist: urllib3<2,>=1.26.18; python_version < "3.10" and platform_system == "Darwin"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-cov<8,>=5; extra == "dev"
+Requires-Dist: ruff<1,>=0.6; extra == "dev"
+Dynamic: license-file
+
+# CompShare CLI
+
+在终端管理优云智算 GPU 实例、镜像、云盘、US3 挂载和团队资源。
+
+- 交互式创建实例，实时查询规格、库存和价格
+- 支持批量生命周期操作、等待状态和跨地域查询
+- 支持可断线恢复的远程任务、状态查询和增量日志读取
+- 支持社区/自定义镜像、云盘、团队额度与账单
+- 默认中文帮助，可切换英文；所有命令支持 JSON 输出
+- 可通过 `compshare ask` 查询产品使用和计费知识
+- 可通过 `compshare feedback` 反馈 CLI 问题和建议
+
+## 安装
+
+```bash
+pip install compshare-cli
+pip install --upgrade compshare-cli
+```
+
+## 配置
+
+```bash
+compshare config --name default
+```
+
+凭证保存在 `~/.config/compshare/config.json`，支持多个配置：
+
+```bash
+compshare config list
+compshare config use production
+compshare --profile production instance list
+```
+
+也可以使用环境变量：
+
+```bash
+export COMPSHARE_PUBLIC_KEY='...'
+export COMPSHARE_PRIVATE_KEY='...'
+```
+
+## 快速开始
+
+```bash
+# 查询、创建和查看实例
+compshare instance search --region cn-sh2 --zone cn-sh2-02
+compshare instance create
+compshare instance list --all
+
+# 连接实例
+compshare instance ssh INSTANCE_ID
+
+# 查看帮助
+compshare -h
+compshare instance -h
+```
+
+## 命令概览
+
+```text
+compshare config     API 凭证配置
+compshare feedback   反馈 CLI 问题或建议
+compshare doctor     配置、鉴权、网络与 SSH 环境诊断
+compshare ask        产品使用和计费问答
+compshare instance   GPU 实例、规格、库存、价格和生命周期
+compshare image      平台、自定义、社区及共享镜像
+compshare storage    云盘和 US3 挂载
+compshare team       团队、邀请、成员额度、账单和审计
+```
+
+## Skill
+
+为 Codex、Claude Code、Cursor 等 AI Agent 安装 CompShare CLI Skill：
+
+```bash
+npx skills add compshare-cn/compshare-cli --skill compshare-cli
+```
+
+完整说明见 [CompShare CLI Skill](skills/compshare-cli/SKILL.md)。
+
+## SDK
+
+如需通过 SDK 集成 CompShare API，可参考独立的
+[CompShare Developer Examples](https://github.com/ucloud/compshare-developer-examples) 仓库。
+其中包含 Python、Go、Java、JavaScript 和 PHP 示例，覆盖 API 鉴权、GPU 实例创建、规格配置和状态查询。

compshare_cli-0.3.5/README.md

@@ -0,0 +1,84 @@
+# CompShare CLI
+
+在终端管理优云智算 GPU 实例、镜像、云盘、US3 挂载和团队资源。
+
+- 交互式创建实例，实时查询规格、库存和价格
+- 支持批量生命周期操作、等待状态和跨地域查询
+- 支持可断线恢复的远程任务、状态查询和增量日志读取
+- 支持社区/自定义镜像、云盘、团队额度与账单
+- 默认中文帮助，可切换英文；所有命令支持 JSON 输出
+- 可通过 `compshare ask` 查询产品使用和计费知识
+- 可通过 `compshare feedback` 反馈 CLI 问题和建议
+
+## 安装
+
+```bash
+pip install compshare-cli
+pip install --upgrade compshare-cli
+```
+
+## 配置
+
+```bash
+compshare config --name default
+```
+
+凭证保存在 `~/.config/compshare/config.json`，支持多个配置：
+
+```bash
+compshare config list
+compshare config use production
+compshare --profile production instance list
+```
+
+也可以使用环境变量：
+
+```bash
+export COMPSHARE_PUBLIC_KEY='...'
+export COMPSHARE_PRIVATE_KEY='...'
+```
+
+## 快速开始
+
+```bash
+# 查询、创建和查看实例
+compshare instance search --region cn-sh2 --zone cn-sh2-02
+compshare instance create
+compshare instance list --all
+
+# 连接实例
+compshare instance ssh INSTANCE_ID
+
+# 查看帮助
+compshare -h
+compshare instance -h
+```
+
+## 命令概览
+
+```text
+compshare config     API 凭证配置
+compshare feedback   反馈 CLI 问题或建议
+compshare doctor     配置、鉴权、网络与 SSH 环境诊断
+compshare ask        产品使用和计费问答
+compshare instance   GPU 实例、规格、库存、价格和生命周期
+compshare image      平台、自定义、社区及共享镜像
+compshare storage    云盘和 US3 挂载
+compshare team       团队、邀请、成员额度、账单和审计
+```
+
+## Skill
+
+为 Codex、Claude Code、Cursor 等 AI Agent 安装 CompShare CLI Skill：
+
+```bash
+npx skills add compshare-cn/compshare-cli --skill compshare-cli
+```
+
+完整说明见 [CompShare CLI Skill](skills/compshare-cli/SKILL.md)。
+
+## SDK
+
+如需通过 SDK 集成 CompShare API，可参考独立的
+[CompShare Developer Examples](https://github.com/ucloud/compshare-developer-examples) 仓库。
+其中包含 Python、Go、Java、JavaScript 和 PHP 示例，覆盖 API 鉴权、GPU 实例创建、规格配置和状态查询。

{compshare_cli-0.3.3 → compshare_cli-0.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "compshare-cli"
-version = "0.3.3"
+dynamic = ["version"]
 description = "Command-line client for CompShare GPU compute"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -39,6 +39,9 @@ dev = [
 compshare = "compshare_cli.cli:main"
 compshare-ssh-askpass = "compshare_cli.ssh:askpass"
 
+[tool.setuptools.dynamic]
+version = { attr = "compshare_cli.__version__" }
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

{compshare_cli-0.3.3 → compshare_cli-0.3.5}/src/compshare_cli/__init__.py

@@ -1,3 +1,3 @@
 """CompShare command-line client."""
 
-__version__ = "0.3.3"
+__version__ = "0.3.5"

{compshare_cli-0.3.3 → compshare_cli-0.3.5}/src/compshare_cli/api.py

@@ -52,11 +52,12 @@ def invoke(
                     continue
                 raise
     except CLIError as error:
-        renderer.error(str(error))
+        renderer.coded_error("configuration_error", str(error))
         raise typer.Exit(1) from error
     except ucloud_exc.RetCodeException as error:
         hint = error_hint(error.action or action, error.code)
-        renderer.error(
+        renderer.coded_error(
+            "api_error",
             _with_hint(error.message or str(error), hint),
             details={
                 "action": error.action,
@@ -67,10 +68,10 @@ def invoke(
         )
         raise typer.Exit(1) from error
     except ucloud_exc.UCloudException as error:
-        renderer.error(str(error))
+        renderer.coded_error("transport_error", str(error))
         raise typer.Exit(1) from error
     except Exception as error:  # SDK transport exceptions are not all UCloudException subclasses.
-        renderer.error(str(error))
+        renderer.coded_error("transport_error", str(error))
         raise typer.Exit(1) from error
 
     if success:
@@ -79,7 +80,7 @@ def invoke(
         renderer.data(response)
     else:
         rows = row_builder(response) if row_builder else response.get(list_key or "") or []
-        renderer.data(response, rows=rows, columns=columns)
+        renderer.data(response, rows=rows, columns=columns, json_list=True)
     return response
 
 
@@ -88,11 +89,14 @@ def call(runtime: Runtime, action: str, params: Dict[str, Any]) -> Dict[str, Any
     try:
         return _sdk(runtime, params).invoke(action, params)
     except CLIError as error:
-        Renderer(runtime.json_output, runtime.show_sensitive).error(str(error))
+        Renderer(runtime.json_output, runtime.show_sensitive).coded_error(
+            "configuration_error", str(error)
+        )
         raise typer.Exit(1) from error
     except ucloud_exc.RetCodeException as error:
         hint = error_hint(error.action or action, error.code)
-        Renderer(runtime.json_output, runtime.show_sensitive).error(
+        Renderer(runtime.json_output, runtime.show_sensitive).coded_error(
+            "api_error",
             _with_hint(error.message or str(error), hint),
             details={
                 "action": error.action,
@@ -103,10 +107,14 @@ def call(runtime: Runtime, action: str, params: Dict[str, Any]) -> Dict[str, Any
         )
         raise typer.Exit(1) from error
     except ucloud_exc.UCloudException as error:
-        Renderer(runtime.json_output, runtime.show_sensitive).error(str(error))
+        Renderer(runtime.json_output, runtime.show_sensitive).coded_error(
+            "transport_error", str(error)
+        )
         raise typer.Exit(1) from error
     except Exception as error:
-        Renderer(runtime.json_output, runtime.show_sensitive).error(str(error))
+        Renderer(runtime.json_output, runtime.show_sensitive).coded_error(
+            "transport_error", str(error)
+        )
         raise typer.Exit(1) from error
 
 
@@ -195,11 +203,14 @@ def download_file(
     try:
         return _sdk(runtime, params).download(action, params)
     except CLIError as error:
-        Renderer(runtime.json_output, runtime.show_sensitive).error(str(error))
+        Renderer(runtime.json_output, runtime.show_sensitive).coded_error(
+            "configuration_error", str(error)
+        )
         raise typer.Exit(1) from error
     except ucloud_exc.RetCodeException as error:
         hint = error_hint(error.action or action, error.code)
-        Renderer(runtime.json_output, runtime.show_sensitive).error(
+        Renderer(runtime.json_output, runtime.show_sensitive).coded_error(
+            "api_error",
             _with_hint(error.message or str(error), hint),
             details={
                 "action": error.action or action,
@@ -210,10 +221,14 @@ def download_file(
         )
         raise typer.Exit(1) from error
     except ucloud_exc.UCloudException as error:
-        Renderer(runtime.json_output, runtime.show_sensitive).error(str(error))
+        Renderer(runtime.json_output, runtime.show_sensitive).coded_error(
+            "transport_error", str(error)
+        )
         raise typer.Exit(1) from error
     except Exception as error:
-        Renderer(runtime.json_output, runtime.show_sensitive).error(str(error))
+        Renderer(runtime.json_output, runtime.show_sensitive).coded_error(
+            "transport_error", str(error)
+        )
         raise typer.Exit(1) from error
 
 

{compshare_cli-0.3.3 → compshare_cli-0.3.5}/src/compshare_cli/cli.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
 import sys
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 
 import click
 import typer
 from typer import core as typer_core
+from typer.completion import completion_init, install_callback
 from typer.main import get_command
 
 from compshare_cli import __version__
@@ -15,7 +16,7 @@ from compshare_cli.commands import feedback as feedback_command
 from compshare_cli.commands import image, instance, storage, team
 from compshare_cli.commands.common import confirm
 from compshare_cli.config import DEFAULT_PROFILE, ConfigStore, Profile
-from compshare_cli.errors import CLIError, UsageError
+from compshare_cli.errors import CLIError, ConfigError, UsageError
 from compshare_cli.i18n import configured_language, localize_command, normalize_language, tr
 from compshare_cli.insights import record_command
 from compshare_cli.output import Renderer
@@ -26,6 +27,8 @@ _TYPER_CLICK_EXCEPTIONS = getattr(_TYPER_CLICK, "exceptions", _TYPER_CLICK)
 _CLICK_EXCEPTIONS = (click.ClickException, _TYPER_CLICK_EXCEPTIONS.ClickException)
 _ABORT_EXCEPTIONS = (click.Abort, _TYPER_CLICK_EXCEPTIONS.Abort)
 
+completion_init()
+
 
 class RootGroup(typer_core.TyperGroup):
     def list_commands(self, ctx):
@@ -42,7 +45,7 @@ app = typer.Typer(
     help="Manage CompShare GPU compute from the terminal.",
     cls=RootGroup,
     no_args_is_help=True,
-    add_completion=True,
+    add_completion=False,
     context_settings={"help_option_names": ["-h", "--help"]},
 )
 app.add_typer(instance.app, name="instance")
@@ -57,9 +60,12 @@ config_app = typer.Typer(
 app.add_typer(config_app, name="config")
 
 
-def _version_callback(value: bool) -> None:
+def _version_callback(ctx: typer.Context, value: bool) -> None:
     if value:
-        typer.echo(__version__)
+        if bool(ctx.params.get("json_output")):
+            Renderer(True, bool(ctx.params.get("show_sensitive"))).data({"version": __version__})
+        else:
+            typer.echo(__version__)
         raise typer.Exit()
 
 
@@ -89,11 +95,13 @@ def root(
     json_output: bool = typer.Option(
         False,
         "--json",
+        is_eager=True,
         help="Emit machine-readable JSON.",
     ),
     show_sensitive: bool = typer.Option(
         False,
         "--show-sensitive",
+        is_eager=True,
         help="Show passwords, IP addresses, access URLs, and login commands.",
     ),
     version_option: bool = typer.Option(
@@ -103,6 +111,13 @@ def root(
         is_eager=True,
         help="Print the CLI version and exit.",
     ),
+    install_completion: bool = typer.Option(
+        None,
+        "--install-completion",
+        callback=install_callback,
+        expose_value=False,
+        help="Install completion for the current shell.",
+    ),
 ) -> None:
     """CompShare CLI."""
     ctx.obj = Runtime(
@@ -182,13 +197,54 @@ def config_set(
 def config_list(ctx: typer.Context) -> None:
     """List credential profiles."""
     store = ConfigStore()
-    current = store.current_profile()
-    profiles = [{"Profile": name, "Active": name == current} for name in store.list_profiles()]
     state = ctx.find_root().obj
+    status = store.credential_status(state.profile_name)
+    source = status["credential_source"]
+    selected = status["selected_profile"]
+    active_profile = selected if source in {"profile", "mixed"} else None
+    profiles = [
+        {
+            "Profile": name,
+            "Active": name == active_profile,
+            "Source": "mixed" if name == active_profile and source == "mixed" else "profile",
+        }
+        for name in store.list_profiles()
+    ]
+    rows = [
+        {
+            **profile,
+            "Source": tr("Profile and environment")
+            if profile["Source"] == "mixed"
+            else tr("Profile file"),
+        }
+        for profile in profiles
+    ]
+    if source == "environment":
+        rows.insert(
+            0,
+            {"Profile": "-", "Active": True, "Source": tr("Environment variables")},
+        )
+    elif source in {"unconfigured", "incomplete"} and not any(
+        profile["Active"] for profile in profiles
+    ):
+        rows.insert(
+            0,
+            {
+                "Profile": selected,
+                "Active": False,
+                "Source": tr("Incomplete credentials")
+                if source == "incomplete"
+                else tr("Not configured"),
+            },
+        )
     Renderer(state.json_output, state.show_sensitive).data(
-        {"current_profile": current, "profiles": profiles},
-        rows=profiles,
-        columns=(("Profile", "PROFILE"), ("Active", "ACTIVE")),
+        {
+            **status,
+            "current_profile": active_profile,
+            "profiles": profiles,
+        },
+        rows=rows,
+        columns=(("Profile", "PROFILE"), ("Active", "ACTIVE"), ("Source", "SOURCE")),
     )
 
 
@@ -270,6 +326,53 @@ def feedback(
     feedback_command.run(ctx.find_root().obj, category, message)
 
 
+def _global_flag_requested(argv: List[str], option: str) -> bool:
+    for token in argv:
+        if token == "--":
+            break
+        if token == option:
+            return True
+    return False
+
+
+def _normalize_global_options(argv: List[str]) -> List[str]:
+    """Move unambiguous root options before the command without crossing --."""
+    global_options: List[str] = []
+    remaining: List[str] = []
+    profile_seen = False
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token == "--":
+            remaining.extend(argv[index:])
+            break
+        if token in {"--json", "--show-sensitive"}:
+            global_options.append(token)
+            index += 1
+            continue
+        if token == "--profile":
+            if profile_seen:
+                raise UsageError(tr("Option --profile may only be specified once."))
+            profile_seen = True
+            if index + 1 >= len(argv) or argv[index + 1].startswith("-"):
+                raise UsageError(tr("Option --profile requires a value."))
+            global_options.extend((token, argv[index + 1]))
+            index += 2
+            continue
+        if token.startswith("--profile="):
+            if profile_seen:
+                raise UsageError(tr("Option --profile may only be specified once."))
+            profile_seen = True
+            if not token.partition("=")[2]:
+                raise UsageError(tr("Option --profile requires a value."))
+            global_options.append(token)
+            index += 1
+            continue
+        remaining.append(token)
+        index += 1
+    return [*global_options, *remaining]
+
+
 def _command_path(command: click.Command, argv: List[str]) -> Optional[str]:
     if not argv or "-h" in argv or "--help" in argv:
         return None
@@ -298,6 +401,77 @@ def _command_path(command: click.Command, argv: List[str]) -> Optional[str]:
     return ".".join(path) or None
 
 
+def _json_help_requested(argv: List[str]) -> bool:
+    for token in argv:
+        if token == "--":
+            return False
+        if token in {"-h", "--help"}:
+            return True
+    return False
+
+
+def _json_help_payload(command: click.Command, argv: List[str]) -> Dict[str, Any]:
+    """Build machine-readable help without invoking Rich's terminal renderer."""
+    current = command
+    path: List[str] = []
+    skip_next = False
+    for token in argv:
+        if skip_next:
+            skip_next = False
+            continue
+        if token in {"-h", "--help", "--"}:
+            break
+        if token in {"--profile", "--lang"}:
+            skip_next = True
+            continue
+        if token.startswith(("--profile=", "--lang=")) or token in {
+            "--json",
+            "--show-sensitive",
+        }:
+            continue
+        if isinstance(current, click.Group) and token in current.commands:
+            current = current.commands[token]
+            path.append(token)
+
+    parameters: List[Dict[str, Any]] = []
+    for parameter in current.params:
+        if isinstance(parameter, click.Option):
+            parameters.append(
+                {
+                    "kind": "option",
+                    "name": parameter.name,
+                    "flags": [*parameter.opts, *parameter.secondary_opts],
+                    "required": parameter.required,
+                    "multiple": parameter.multiple,
+                    "help": parameter.help,
+                }
+            )
+        elif isinstance(parameter, click.Argument):
+            parameters.append(
+                {
+                    "kind": "argument",
+                    "name": parameter.name,
+                    "required": parameter.required,
+                    "multiple": parameter.nargs != 1,
+                }
+            )
+    commands = []
+    if isinstance(current, click.Group):
+        commands = [
+            {"name": name, "help": child.get_short_help_str()}
+            for name in current.list_commands(click.Context(current))
+            if (child := current.get_command(click.Context(current), name)) is not None
+            and not child.hidden
+        ]
+    command_name = " ".join(["compshare", *path])
+    return {
+        "command_path": command_name,
+        "help": current.help,
+        "parameters": parameters,
+        "commands": commands,
+    }
+
+
 def _requested_language(argv: List[str]) -> Optional[str]:
     """Return the last root --lang value before the command, if present."""
     requested: Optional[str] = None
@@ -338,8 +512,10 @@ def main(args: Optional[List[str]] = None) -> None:
     if not argv:
         argv = ["-h"]
     telemetry_command: Optional[str] = None
-    show_sensitive = "--show-sensitive" in argv
+    json_output = _global_flag_requested(argv, "--json")
+    show_sensitive = _global_flag_requested(argv, "--show-sensitive")
     try:
+        argv = _normalize_global_options(argv)
         requested_language = _requested_language(argv)
         if requested_language is None:
             language = configured_language()
@@ -347,23 +523,27 @@ def main(args: Optional[List[str]] = None) -> None:
             language = normalize_language(requested_language)
             ConfigStore().save_language(language)
         command = localize_command(get_command(app), language)
-        telemetry_command = _command_path(command, original_argv)
-        result = command.main(args=argv, prog_name="compshare", standalone_mode=False)
+        telemetry_command = _command_path(command, argv)
+        if json_output and _json_help_requested(argv):
+            Renderer(True, show_sensitive).data(_json_help_payload(command, argv))
+            result = None
+        else:
+            result = command.main(args=argv, prog_name="compshare", standalone_mode=False)
+    except ConfigError as error:
+        Renderer(json_output, show_sensitive).coded_error("configuration_error", str(error))
+        raise SystemExit(2) from error
+    except UsageError as error:
+        Renderer(json_output, show_sensitive).coded_error("invalid_usage", str(error))
+        raise SystemExit(2) from error
     except CLIError as error:
-        Renderer("--json" in argv, show_sensitive).error(str(error))
+        Renderer(json_output, show_sensitive).coded_error("cli_error", str(error))
         raise SystemExit(2) from error
     except _CLICK_EXCEPTIONS as error:
         message = error.format_message()
-        if "--json" in argv and "No such option: --json" in message:
-            hint = tr(
-                "Global option --json must appear before the command, for example: "
-                "compshare --json instance list."
-            )
-            message = f"{message} {hint}"
-        Renderer("--json" in argv, show_sensitive).error(message)
+        Renderer(json_output, show_sensitive).coded_error("invalid_usage", message)
         raise SystemExit(error.exit_code) from error
     except _ABORT_EXCEPTIONS as error:
-        Renderer("--json" in argv, show_sensitive).error(tr("Aborted"))
+        Renderer(json_output, show_sensitive).coded_error("aborted", tr("Aborted"))
         raise SystemExit(1) from error
     finally:
         if telemetry_command:

{compshare_cli-0.3.3 → compshare_cli-0.3.5}/src/compshare_cli/commands/doctor.py

@@ -127,6 +127,11 @@ def run(state: Runtime) -> None:
 
     ok = not any(item["Status"] == "Failed" for item in checks)
     payload = {"ok": ok, "checks": checks}
+    if not ok:
+        payload["error"] = {
+            "code": "diagnostic_failed",
+            "message": tr("One or more diagnostic checks failed."),
+        }
     Renderer(state.json_output, state.show_sensitive).data(
         payload,
         rows=checks,

{compshare_cli-0.3.3 → compshare_cli-0.3.5}/src/compshare_cli/commands/image.py

@@ -250,6 +250,8 @@ def list_images(
         response,
         rows=rows,
         columns=IMAGE_COLUMNS,
+        json_list=True,
+        metadata={"source": source, "all": all_results},
     )
 
 
@@ -293,7 +295,13 @@ def show(
             ("PRICE/H", item.get("Price")),
             ("DESCRIPTION", item.get("Description")),
         ],
-        response=response,
+        response={
+            "Action": response.get("Action"),
+            "RetCode": response.get("RetCode"),
+            "request_uuid": response.get("request_uuid"),
+            "source": source,
+            "image": item,
+        },
     )