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

{compshare_cli-0.3.1 → compshare_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compshare-cli
-Version: 0.3.1
+Version: 0.3.3
 Summary: Command-line client for CompShare GPU compute
 Author: CompShare
 License-Expression: Apache-2.0
@@ -35,13 +35,14 @@ Dynamic: license-file
 - 可通过 `compshare feedback` 反馈 CLI 问题和建议
 - 基于官方 [`ucloud-sdk-python3`](https://github.com/ucloud/ucloud-sdk-python3)
 
-当前版本：`0.3.1`，要求 Python 3.9 或更高版本。
+当前版本：`0.3.3`，要求 Python 3.9 或更高版本。
 
 ## 安装
 
 ```bash
 pip install compshare-cli
 compshare -h
+compshare --version
 ```
 
 本地开发：
@@ -101,6 +102,11 @@ compshare instance search --region cn-sh2 --zone cn-sh2-02 \
   --gpu 4090 --image IMAGE_ID --available
 compshare instance list --all
 
+# 聚焦查看实例信息；多个分组可组合
+compshare instance show INSTANCE_ID --ip --softwares
+compshare instance show INSTANCE_ID --spec --disks --billing
+compshare instance show INSTANCE_ID --image --status
+
 # 交互式创建
 compshare instance create
 
@@ -116,9 +122,15 @@ compshare instance ssh INSTANCE_ID --no-auto-password
 # 自动登录后执行远程命令；远程参数用 -- 与 CLI 选项分隔
 compshare instance ssh INSTANCE_ID -- nvidia-smi --query-gpu=name
 compshare instance ssh INSTANCE_ID -- 'cd /workspace && python train.py'
-# 上传本地文件或目录，目录会自动递归复制
-compshare instance scp INSTANCE_ID ./model.bin /workspace/model.bin
-compshare instance scp INSTANCE_ID ./dataset /workspace/dataset
+# Agent/脚本：执行并返回 ok、phase、exit_code、stdout、stderr、error
+compshare --json instance ssh INSTANCE_ID -- nvidia-smi
+# 强制刷新或禁用本地 SSH 连接缓存
+compshare instance ssh INSTANCE_ID --refresh
+compshare instance ssh INSTANCE_ID --no-cache
+# 在本地与实例间双向复制；实例路径以 : 开头，目录会自动递归复制
+compshare instance cp INSTANCE_ID ./model.bin :/workspace/model.bin
+compshare instance cp INSTANCE_ID ./dataset :/workspace/dataset
+compshare instance cp INSTANCE_ID :/workspace/result ./result
 
 # 产品问答
 compshare ask "按量实例关机以后，云硬盘还收费吗？"
@@ -143,16 +155,44 @@ compshare instance create \
 
 使用 `--dry-run` 只检查库存、价格和请求，不创建资源。
 
+本地实例模板可以保存常用创建参数，不依赖控制台或后端模板接口：
+
+```bash
+compshare instance template create training-4090 \
+  --description '4090 训练环境' \
+  --gpu 4090 \
+  --count 1 \
+  --cpu 16 \
+  --memory 64GiB \
+  --image IMAGE_ID \
+  --region cn-sh2 \
+  --zone cn-sh2-02 \
+  --disk 100GiB \
+  --charge Postpay
+
+compshare instance template list
+compshare instance template show training-4090
+compshare instance create --template training-4090 --yes
+
+# 本次显式参数优先于模板值
+compshare instance create --template training-4090 --cpu 32 --memory 128GiB --yes
+```
+
+模板存放在 `~/.config/compshare/instance-templates.json`；可用
+`compshare instance template path` 查看实际路径。模板只保存实例创建参数，不保存 API
+凭证、`--yes`、`--show-sensitive` 或其他执行控制选项。
+
 ## 功能入口
 
 ```text
+compshare config     API 凭证配置
+compshare feedback   反馈 CLI 问题或建议
+compshare doctor     配置、鉴权、网络与 SSH 环境诊断
+compshare ask        产品使用和计费问答
 compshare instance   GPU 实例、规格、库存、价格和生命周期
 compshare image      平台、自定义、社区及共享镜像
 compshare storage    云盘和 US3 挂载
 compshare team       团队、邀请、成员额度、账单和审计
-compshare doctor     配置、鉴权、网络与 SSH 环境诊断
-compshare ask        产品使用和计费问答
-compshare feedback   反馈 CLI 问题或建议
 ```
 
 ## 产品问答
@@ -186,53 +226,79 @@ compshare instance -h
 compshare instance create -h
 ```
 
+## 命令补全
+
+CLI 支持 Bash、Zsh、Fish 和 PowerShell 命令补全。为当前 Shell 自动安装：
+
+```bash
+compshare --install-completion
+```
+
+如需检查、复制或自行加载补全脚本：
+
+```bash
+compshare --show-completion
+```
+
 ## 脚本调用
 
 `--json`、`--profile` 和 `--show-sensitive` 是全局选项，必须放在子命令前：
 
 ```bash
 compshare --json instance list --status Running --all
-compshare --profile production image list --source community --region cn-sh2 --zone cn-sh2-02
+compshare --profile production image list --source community
 compshare --json --show-sensitive instance show uhost-xxxxxxxx
 ```
 
 JSON 模式不会启动交互向导。生命周期操作可使用 `--wait`、`--no-wait` 和
 `--timeout` 控制等待行为；部分批量操作失败时，CLI 返回非零退出码。默认输出会递归隐藏
 密码、IP、访问 URL 和登录命令；只有显式指定 `--show-sensitive` 才会输出原值。
+`instance show` 可使用 `--ip`、`--softwares`、`--spec`、`--disks`、`--billing`、
+`--image` 和 `--status` 聚焦输出一个或多个信息分组；不传这些选项时保持完整摘要。
 
 Region 和 Zone 是资源参数，放在对应子命令后：
 
 ```bash
-compshare instance list --region cn-sh2
+compshare instance list --region cn-sh2 --zone cn-sh2-02
 compshare instance create --region cn-sh2 --zone cn-sh2-02
-compshare image list --source custom --region cn-sh2 --zone cn-sh2-02
+compshare image list --source custom
+compshare storage disk list
 ```
 
-CLI 不保存或自动注入默认 Region/Zone。非交互式地域资源操作需要显式传入；按实例 ID
+镜像列表、网络检测和软件端口列表可进行全局查询，Region/Zone 只是可选过滤条件。CLI
+不保存或自动注入默认 Region/Zone；确实依赖地域的资源操作仍需显式传入。按实例 ID
 执行的生命周期操作使用 `DescribeCompShareInstance` 响应中的 Region 和 Zone；响应缺少任一
 字段时会停止操作，不会从 Zone 推导或用请求 Region 补齐。
 
 ## 语言
 
 ```bash
-compshare lang en
-compshare lang zh
-compshare lang       # 查看当前语言
+compshare --lang en --help
+compshare --lang zh --help
 ```
 
-也可以通过 `COMPSHARE_LANG=en` 临时覆盖。
+`--lang` 会保存所选语言，后续命令继续使用；也可以通过 `COMPSHARE_LANG=en` 临时覆盖。
 
 ## 安全说明
 
 - 配置目录和文件分别使用 `0700`、`0600` 权限。
+- 本地实例模板文件同样使用 `0600` 权限，所在目录使用 `0700` 权限。
 - API 私钥不会出现在命令输出中。
 - 默认使用 `***` 隐藏密码、私钥、IP、访问 URL、令牌和登录命令，包括嵌套 JSON 字段。
 - `instance ssh` 在支持的交互式终端中通过伪终端自动填写登录密码，不会打印密码或将其放入进程参数。
 - 自动登录会接受首次出现的 SSH 主机密钥；已记录主机的密钥发生变化时仍会拒绝连接。
 - `instance ssh INSTANCE_ID -- COMMAND` 可非交互执行远程命令，透传命令输出和退出码。
-- `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 可自动认证并上传本地文件或目录。
+- `--json instance ssh INSTANCE_ID -- COMMAND` 会真实执行命令，并结构化返回退出码、标准输出、标准错误及连接/认证错误阶段。
+- `--json` 始终以 UTF-8 字节输出，不依赖 Windows 活动代码页或终端编码。
+- `instance ssh` 默认将 API 返回的 SSH 命令和密码按 profile/实例缓存 1 小时；Windows 使用当前用户的 DPAPI 加密密码，其他平台将缓存文件权限限制为当前用户。可用 `--refresh` 强制更新、`--no-cache` 禁用；重置密码和重装实例会清除对应缓存。
+- 实例创建是异步操作；`instance create` 默认等待到 `Running`，显式使用 `--no-wait` 才会在创建接口返回后立即退出。`instance ssh` 也会默认等待实例运行后再连接。
+- `instance cp INSTANCE_ID SOURCE DESTINATION` 可自动认证并双向复制文件或目录；实例侧路径
+  使用 `:/path` 表示。旧的 `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 上传语法继续兼容。
+- `--json instance cp ...` 会真实执行复制，并返回 `ok`、`phase`、`exit_code`、
+  `stdout`、`stderr` 和 `error`；只有显式使用 `--print` 才仅输出命令。
 - `--show-sensitive` 会恢复这些字段的原始值；请勿在共享终端、CI 日志或 Agent 会话中使用。
-- 删除、关机、重启、重装和改配等操作默认要求确认。
+- 删除、关机、重启、重装和改配等操作默认要求输入 `y` 或 `n` 确认；空输入或无效输入
+  最多重试三次。JSON 模式不启动确认提示，执行这类操作必须显式使用 `--yes`。
 
 ## 开发校验
 

{compshare_cli-0.3.1 → compshare_cli-0.3.3}/README.md

@@ -10,13 +10,14 @@
 - 可通过 `compshare feedback` 反馈 CLI 问题和建议
 - 基于官方 [`ucloud-sdk-python3`](https://github.com/ucloud/ucloud-sdk-python3)
 
-当前版本：`0.3.1`，要求 Python 3.9 或更高版本。
+当前版本：`0.3.3`，要求 Python 3.9 或更高版本。
 
 ## 安装
 
 ```bash
 pip install compshare-cli
 compshare -h
+compshare --version
 ```
 
 本地开发：
@@ -76,6 +77,11 @@ compshare instance search --region cn-sh2 --zone cn-sh2-02 \
   --gpu 4090 --image IMAGE_ID --available
 compshare instance list --all
 
+# 聚焦查看实例信息；多个分组可组合
+compshare instance show INSTANCE_ID --ip --softwares
+compshare instance show INSTANCE_ID --spec --disks --billing
+compshare instance show INSTANCE_ID --image --status
+
 # 交互式创建
 compshare instance create
 
@@ -91,9 +97,15 @@ compshare instance ssh INSTANCE_ID --no-auto-password
 # 自动登录后执行远程命令；远程参数用 -- 与 CLI 选项分隔
 compshare instance ssh INSTANCE_ID -- nvidia-smi --query-gpu=name
 compshare instance ssh INSTANCE_ID -- 'cd /workspace && python train.py'
-# 上传本地文件或目录，目录会自动递归复制
-compshare instance scp INSTANCE_ID ./model.bin /workspace/model.bin
-compshare instance scp INSTANCE_ID ./dataset /workspace/dataset
+# Agent/脚本：执行并返回 ok、phase、exit_code、stdout、stderr、error
+compshare --json instance ssh INSTANCE_ID -- nvidia-smi
+# 强制刷新或禁用本地 SSH 连接缓存
+compshare instance ssh INSTANCE_ID --refresh
+compshare instance ssh INSTANCE_ID --no-cache
+# 在本地与实例间双向复制；实例路径以 : 开头，目录会自动递归复制
+compshare instance cp INSTANCE_ID ./model.bin :/workspace/model.bin
+compshare instance cp INSTANCE_ID ./dataset :/workspace/dataset
+compshare instance cp INSTANCE_ID :/workspace/result ./result
 
 # 产品问答
 compshare ask "按量实例关机以后，云硬盘还收费吗？"
@@ -118,16 +130,44 @@ compshare instance create \
 
 使用 `--dry-run` 只检查库存、价格和请求，不创建资源。
 
+本地实例模板可以保存常用创建参数，不依赖控制台或后端模板接口：
+
+```bash
+compshare instance template create training-4090 \
+  --description '4090 训练环境' \
+  --gpu 4090 \
+  --count 1 \
+  --cpu 16 \
+  --memory 64GiB \
+  --image IMAGE_ID \
+  --region cn-sh2 \
+  --zone cn-sh2-02 \
+  --disk 100GiB \
+  --charge Postpay
+
+compshare instance template list
+compshare instance template show training-4090
+compshare instance create --template training-4090 --yes
+
+# 本次显式参数优先于模板值
+compshare instance create --template training-4090 --cpu 32 --memory 128GiB --yes
+```
+
+模板存放在 `~/.config/compshare/instance-templates.json`；可用
+`compshare instance template path` 查看实际路径。模板只保存实例创建参数，不保存 API
+凭证、`--yes`、`--show-sensitive` 或其他执行控制选项。
+
 ## 功能入口
 
 ```text
+compshare config     API 凭证配置
+compshare feedback   反馈 CLI 问题或建议
+compshare doctor     配置、鉴权、网络与 SSH 环境诊断
+compshare ask        产品使用和计费问答
 compshare instance   GPU 实例、规格、库存、价格和生命周期
 compshare image      平台、自定义、社区及共享镜像
 compshare storage    云盘和 US3 挂载
 compshare team       团队、邀请、成员额度、账单和审计
-compshare doctor     配置、鉴权、网络与 SSH 环境诊断
-compshare ask        产品使用和计费问答
-compshare feedback   反馈 CLI 问题或建议
 ```
 
 ## 产品问答
@@ -161,53 +201,79 @@ compshare instance -h
 compshare instance create -h
 ```
 
+## 命令补全
+
+CLI 支持 Bash、Zsh、Fish 和 PowerShell 命令补全。为当前 Shell 自动安装：
+
+```bash
+compshare --install-completion
+```
+
+如需检查、复制或自行加载补全脚本：
+
+```bash
+compshare --show-completion
+```
+
 ## 脚本调用
 
 `--json`、`--profile` 和 `--show-sensitive` 是全局选项，必须放在子命令前：
 
 ```bash
 compshare --json instance list --status Running --all
-compshare --profile production image list --source community --region cn-sh2 --zone cn-sh2-02
+compshare --profile production image list --source community
 compshare --json --show-sensitive instance show uhost-xxxxxxxx
 ```
 
 JSON 模式不会启动交互向导。生命周期操作可使用 `--wait`、`--no-wait` 和
 `--timeout` 控制等待行为；部分批量操作失败时，CLI 返回非零退出码。默认输出会递归隐藏
 密码、IP、访问 URL 和登录命令；只有显式指定 `--show-sensitive` 才会输出原值。
+`instance show` 可使用 `--ip`、`--softwares`、`--spec`、`--disks`、`--billing`、
+`--image` 和 `--status` 聚焦输出一个或多个信息分组；不传这些选项时保持完整摘要。
 
 Region 和 Zone 是资源参数，放在对应子命令后：
 
 ```bash
-compshare instance list --region cn-sh2
+compshare instance list --region cn-sh2 --zone cn-sh2-02
 compshare instance create --region cn-sh2 --zone cn-sh2-02
-compshare image list --source custom --region cn-sh2 --zone cn-sh2-02
+compshare image list --source custom
+compshare storage disk list
 ```
 
-CLI 不保存或自动注入默认 Region/Zone。非交互式地域资源操作需要显式传入；按实例 ID
+镜像列表、网络检测和软件端口列表可进行全局查询，Region/Zone 只是可选过滤条件。CLI
+不保存或自动注入默认 Region/Zone；确实依赖地域的资源操作仍需显式传入。按实例 ID
 执行的生命周期操作使用 `DescribeCompShareInstance` 响应中的 Region 和 Zone；响应缺少任一
 字段时会停止操作，不会从 Zone 推导或用请求 Region 补齐。
 
 ## 语言
 
 ```bash
-compshare lang en
-compshare lang zh
-compshare lang       # 查看当前语言
+compshare --lang en --help
+compshare --lang zh --help
 ```
 
-也可以通过 `COMPSHARE_LANG=en` 临时覆盖。
+`--lang` 会保存所选语言，后续命令继续使用；也可以通过 `COMPSHARE_LANG=en` 临时覆盖。
 
 ## 安全说明
 
 - 配置目录和文件分别使用 `0700`、`0600` 权限。
+- 本地实例模板文件同样使用 `0600` 权限，所在目录使用 `0700` 权限。
 - API 私钥不会出现在命令输出中。
 - 默认使用 `***` 隐藏密码、私钥、IP、访问 URL、令牌和登录命令，包括嵌套 JSON 字段。
 - `instance ssh` 在支持的交互式终端中通过伪终端自动填写登录密码，不会打印密码或将其放入进程参数。
 - 自动登录会接受首次出现的 SSH 主机密钥；已记录主机的密钥发生变化时仍会拒绝连接。
 - `instance ssh INSTANCE_ID -- COMMAND` 可非交互执行远程命令，透传命令输出和退出码。
-- `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 可自动认证并上传本地文件或目录。
+- `--json instance ssh INSTANCE_ID -- COMMAND` 会真实执行命令，并结构化返回退出码、标准输出、标准错误及连接/认证错误阶段。
+- `--json` 始终以 UTF-8 字节输出，不依赖 Windows 活动代码页或终端编码。
+- `instance ssh` 默认将 API 返回的 SSH 命令和密码按 profile/实例缓存 1 小时；Windows 使用当前用户的 DPAPI 加密密码，其他平台将缓存文件权限限制为当前用户。可用 `--refresh` 强制更新、`--no-cache` 禁用；重置密码和重装实例会清除对应缓存。
+- 实例创建是异步操作；`instance create` 默认等待到 `Running`，显式使用 `--no-wait` 才会在创建接口返回后立即退出。`instance ssh` 也会默认等待实例运行后再连接。
+- `instance cp INSTANCE_ID SOURCE DESTINATION` 可自动认证并双向复制文件或目录；实例侧路径
+  使用 `:/path` 表示。旧的 `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 上传语法继续兼容。
+- `--json instance cp ...` 会真实执行复制，并返回 `ok`、`phase`、`exit_code`、
+  `stdout`、`stderr` 和 `error`；只有显式使用 `--print` 才仅输出命令。
 - `--show-sensitive` 会恢复这些字段的原始值；请勿在共享终端、CI 日志或 Agent 会话中使用。
-- 删除、关机、重启、重装和改配等操作默认要求确认。
+- 删除、关机、重启、重装和改配等操作默认要求输入 `y` 或 `n` 确认；空输入或无效输入
+  最多重试三次。JSON 模式不启动确认提示，执行这类操作必须显式使用 `--yes`。
 
 ## 开发校验
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "compshare-cli"
-version = "0.3.1"
+version = "0.3.3"
 description = "Command-line client for CompShare GPU compute"
 readme = "README.md"
 requires-python = ">=3.9"

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

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

{compshare_cli-0.3.1 → compshare_cli-0.3.3}/src/compshare_cli/actions.py

@@ -34,8 +34,9 @@ INSTANCE_ACTIONS = frozenset(
 
 IMAGE_ACTIONS = frozenset(
     {
-        "AddFavoriteImage",
+        "CreateCompShareImageFavorite",
         "CreateCompShareCustomImage",
+        "DeleteCompShareImageFavorite",
         "DescribeCommunityImages",
         "DescribeCompShareCustomImages",
         "DescribeCompShareImages",
@@ -47,7 +48,6 @@ IMAGE_ACTIONS = frozenset(
         "GetCompShareImageCreateProgress",
         "ModifyCompShareImageShareAccount",
         "PublishCompShareImage",
-        "RemoveFavoriteImage",
         "TerminateCompShareCustomImage",
         "UpdateCompShareImage",
     }
@@ -59,6 +59,7 @@ STORAGE_ACTIONS = frozenset(
         "AttachUS3",
         "CreateAndAttachCompshareDisk",
         "DeleteCompshareDisk",
+        "DescribeCompshareDisk",
         "DetachCompshareDisk",
         "GetCompShareAttachedDiskUpgradePrice",
         "ResizeCompShareDisk",
@@ -89,9 +90,16 @@ TEAM_ACTIONS = frozenset(
 
 PUBLIC_ACTIONS = INSTANCE_ACTIONS | IMAGE_ACTIONS | STORAGE_ACTIONS | TEAM_ACTIONS
 
-# Public API actions intentionally exposed as CLI placeholders until their
-# production request contract is ready.
-COMING_SOON_ACTIONS = frozenset({"GetCompShareInstanceMonitor"})
+# No unavailable API actions are currently exposed as placeholders.
+COMING_SOON_ACTIONS = frozenset()
 
-# Documented publicly but unavailable in the production API (RetCode 161).
-UNAVAILABLE_ACTIONS = frozenset({"DescribeFavoriteImages"})
+# Documented publicly but unavailable in the production API.
+UNAVAILABLE_ACTIONS = frozenset(
+    {
+        "AddFavoriteImage",
+        "DescribeFavoriteImages",
+        "GetCompShareInstanceMonitor",
+        "GetSoftwareURL",
+        "RemoveFavoriteImage",
+    }
+)

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

@@ -228,10 +228,6 @@ def error_hint(action: str, code: int) -> Optional[str]:
         ("GetCompShareInstanceMonitor", 230): (
             "This production endpoint is currently incompatible; use the console for monitoring."
         ),
-        ("GetSoftwareURL", 230): (
-            "This production endpoint currently rejects its action; "
-            "use instance show or the console."
-        ),
     }
     return tr(hints[(action, code)]) if (action, code) in hints else None