@viceme-ai/cli 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +26 -11
  3. package/README.zh.md +26 -11
  4. package/checksums.txt +6 -6
  5. package/docs/releasing.md +12 -5
  6. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.3.1] - 2026-07-20
4
+
5
+ ### Fixes
6
+
7
+ - isolate npm cache and classify failures (`b778aa1`)
8
+
9
+ ### Other Changes
10
+
11
+ - clarify workflow check names (`cf7da33`)
12
+
13
+ ## [0.3.0] - 2026-07-20
14
+
15
+ ### Features
16
+
17
+ - add profile management (`fec286e`)
18
+
3
19
  ## [0.2.1] - 2026-07-20
4
20
 
5
21
  ### Fixes
package/README.md CHANGED
@@ -2,15 +2,15 @@
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@viceme-ai/cli.svg)](https://www.npmjs.com/package/@viceme-ai/cli)
4
4
  [![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
5
- [![CLI quality gates](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
5
+ [![CLI PR checks](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
6
6
 
7
7
  [中文版](./README.zh.md) | [English](./README.md)
8
8
 
9
9
  The official command-line client and Agent Skill for publishing external Skills as stable, shareable Viceme Agents. It is built for AI coding tools such as Codex and Claude Code: the Agent Skill understands user intent, while the CLI provides the deterministic authentication, upload, publication, and status protocol.
10
10
 
11
- [Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Regions](#regions) · [Commands](#command-overview) · [Output contract](#json-output-contract) · [Security](#security-and-risk-controls) · [Development](#development)
11
+ [Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Regions & profiles](#regions--profiles) · [Commands](#command-overview) · [Output contract](#json-output-contract) · [Security](#security-and-risk-controls) · [Development](#development)
12
12
 
13
- > **Rollout status:** the Core publication transport and stable-link path are implemented behind a controlled allowlist. Public rollout remains blocked until the exact Candidate preview, test run, and result-confirmation gate is complete. The current `--yes` confirms the publication request; it is not proof that the user reviewed the final Candidate.
13
+ > **Rollout status:** the Core publication transport and stable-link path are implemented. Public rollout remains blocked until the exact Candidate preview, test run, and result-confirmation gate is complete. The current `--yes` confirms the publication request; it is not proof that the user reviewed the final Candidate.
14
14
 
15
15
  ## Why Viceme CLI?
16
16
 
@@ -103,6 +103,7 @@ viceme auth login --device-code <device-code>
103
103
  ```
104
104
 
105
105
  If authorization is still pending, reuse the same device code before it expires. Do not start a second device flow unless the original one has expired.
106
+ For a non-default profile, pass the same global `--profile <name>` when starting and continuing device login; the start result reports the effective `profile` and `region`.
106
107
 
107
108
  **Step 4 — Verify**
108
109
 
@@ -122,18 +123,31 @@ viceme skill inspect https://github.com/acme/poster-skill
122
123
 
123
124
  Inspection is read-only. Follow the bundled `viceme` Skill for source-specific handling, Target selection, confirmation, bounded job waiting, and result reporting. Public publication remains blocked until the exact Candidate confirmation gate described above is complete.
124
125
 
125
- ## Regions
126
+ ## Regions & Profiles
126
127
 
127
- Viceme exposes one product-level region choice during installation:
128
+ Each profile selects one Viceme region:
128
129
 
129
130
  | Region | Install command | API endpoint |
130
131
  |---|---|---|
131
132
  | China | `viceme install` | `https://api.viceme.cn` |
132
133
  | International | `viceme install --region global` | `https://api.viceme.ai` |
133
134
 
134
- The selected value is persisted as `region=cn|global`; later commands use it automatically. Credentials are isolated by region, so a China token is never reused against the international API, or vice versa.
135
+ The first install creates the `default` profile. Non-sensitive configuration is stored in `~/.viceme-cli/config.json`; access tokens remain exclusively in the operating-system keychain. Credentials are isolated by both profile and region.
135
136
 
136
- There is no public API URL, profile, or output-format configuration. For local development only, set `VICEME_API_BASE_URL` in the terminal environment.
137
+ ```bash
138
+ viceme profile list
139
+ viceme profile add --name work --region global --use
140
+ viceme profile use default
141
+ viceme --profile work auth status
142
+ viceme profile rename work company
143
+ viceme profile remove company
144
+ ```
145
+
146
+ `profile use` changes the persistent active profile; the global `--profile` flag overrides only one command. AI Agents must not switch or remove profiles unless the user explicitly requests it.
147
+
148
+ `VICEME_CLI_CONFIG_DIR` can override the config root. Local API development still uses the process-only `VICEME_API_BASE_URL`; it is never persisted in a profile.
149
+
150
+ Update checks query the npm registry directly and store only the last successful version result in `~/.viceme-cli/update-state.json`. A result is used as a fallback for at most 24 hours when the registry is temporarily unavailable. npm operations launched by `viceme install` or `viceme update` use the isolated `~/.viceme-cli/npm-cache`, so a broken user-level `~/.npm` cache does not block the CLI. Both files are non-secret and can be deleted safely; credentials never enter either cache.
137
151
 
138
152
  ## Agent Skills
139
153
 
@@ -160,10 +174,10 @@ viceme skills doctor
160
174
 
161
175
  | Command | Purpose |
162
176
  |---|---|
163
- | `viceme auth status` | Show whether the current region is authenticated |
177
+ | `viceme auth status` | Show whether the current profile is authenticated |
164
178
  | `viceme auth login --no-wait` | Start device authorization and return immediately |
165
179
  | `viceme auth login --device-code <code>` | Complete a previously started authorization |
166
- | `viceme auth logout` | Revoke and remove the current region credential |
180
+ | `viceme auth logout` | Revoke and remove the current profile credential |
167
181
 
168
182
  Tokens are stored only in the operating-system keychain. There is no plaintext token fallback, and successful login output never contains the access or refresh token.
169
183
 
@@ -204,8 +218,9 @@ viceme skill publish --file ./poster-skill-v2.zip \
204
218
 
205
219
  | Command group | Purpose |
206
220
  |---|---|
207
- | `viceme install` | Install the persistent launcher, Agent Skill, and region configuration |
221
+ | `viceme install` | Install the persistent launcher, Agent Skill, and default profile |
208
222
  | `viceme auth` | Start, complete, inspect, or revoke device authentication |
223
+ | `viceme profile` | Add, list, switch, rename, or remove local profiles |
209
224
  | `viceme skill inspect` | Freeze and inspect a source candidate without publishing |
210
225
  | `viceme skill publish` | Create or update a stable Skill Agent publication |
211
226
  | `viceme skill target` | Resolve existing logical Agent Targets and versions |
@@ -266,7 +281,7 @@ Determine command success from the process exit code or `ok == true`. A successf
266
281
  - **No source execution** — the CLI and compiler do not execute third-party scripts, binaries, shell fragments, marketplace commands, or copied instructions.
267
282
  - **Explicit public mutation** — publishing and cancellation require `--yes`; exit code `10` means the Agent must obtain confirmation, not silently retry.
268
283
  - **Safe preview** — use `--dry-run` on inspect or publish when the user needs to review the planned request without network or publication side effects.
269
- - **Credential isolation** — credentials stay in the OS keychain and are namespaced by region.
284
+ - **Credential isolation** — credentials stay in the OS keychain and are namespaced by profile and region.
270
285
  - **Immutable inputs** — inspection binds publication to an immutable source snapshot rather than re-reading a floating URL later.
271
286
  - **Bounded waiting** — `job wait` has a maximum duration and returns the latest durable state without cancelling the workflow.
272
287
  - **Verified distribution** — the npm launcher downloads the binary for its exact package version from GitHub or a binary mirror and verifies it against the checksum manifest bundled in the npm package before activation.
package/README.zh.md CHANGED
@@ -2,15 +2,15 @@
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@viceme-ai/cli.svg)](https://www.npmjs.com/package/@viceme-ai/cli)
4
4
  [![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
5
- [![CLI quality gates](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
5
+ [![CLI PR checks](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
6
6
 
7
7
  [中文版](./README.zh.md) | [English](./README.md)
8
8
 
9
9
  Viceme 官方命令行客户端与 Agent Skill，用于将外部 Skill 发布为稳定、可分享的 Viceme Agent。它面向 Codex、Claude Code 等 AI 编程工具：Agent Skill 负责理解用户意图，CLI 负责确定性的认证、上传、发布和状态协议。
10
10
 
11
- [安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [区域](#区域) · [命令](#命令概览) · [输出契约](#json-输出契约) · [安全](#安全与风险控制) · [开发](#开发)
11
+ [安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [区域与-profile](#区域与-profile) · [命令](#命令概览) · [输出契约](#json-输出契约) · [安全](#安全与风险控制) · [开发](#开发)
12
12
 
13
- > **开放状态：** Core 发布传输和稳定链接链路已在受控白名单后实现。正式对外开放仍取决于精确 Candidate 预览、试运行和结果确认门的完成。当前 `--yes` 只确认发起发布请求，并不代表用户已经审阅最终 Candidate。
13
+ > **开放状态：** Core 发布传输和稳定链接链路已经实现。正式对外开放仍取决于精确 Candidate 预览、试运行和结果确认门的完成。当前 `--yes` 只确认发起发布请求，并不代表用户已经审阅最终 Candidate。
14
14
 
15
15
  ## 为什么选择 Viceme CLI？
16
16
 
@@ -103,6 +103,7 @@ viceme auth login --device-code <device-code>
103
103
  ```
104
104
 
105
105
  如果授权仍处于等待状态，应在过期前继续使用同一个 device code。只有原流程已过期时才能重新发起设备登录。
106
+ 使用非默认 Profile 时，启动和继续设备登录必须传入同一个全局 `--profile <name>`；启动结果会返回实际的 `profile` 与 `region`。
106
107
 
107
108
  **第 4 步 — 验证**
108
109
 
@@ -122,18 +123,31 @@ viceme skill inspect https://github.com/acme/poster-skill
122
123
 
123
124
  inspect 是只读操作。后续应按照随包发布的 `viceme` Skill 处理不同来源、Target 选择、用户确认、有界任务等待和结果返回。在上方所述的精确 Candidate 确认门完成前，公开发布流程仍保持关闭。
124
125
 
125
- ## 区域
126
+ ## 区域与 Profile
126
127
 
127
- Viceme 在安装时只提供一个产品级区域选择：
128
+ 每个 Profile 独立选择一个 Viceme 区域：
128
129
 
129
130
  | 区域 | 安装命令 | API 地址 |
130
131
  |---|---|---|
131
132
  | 中国区 | `viceme install` | `https://api.viceme.cn` |
132
133
  | 国际区 | `viceme install --region global` | `https://api.viceme.ai` |
133
134
 
134
- 选择结果保存为 `region=cn|global`，后续命令会自动使用。不同区域的凭证彼此隔离，中国区令牌不会用于国际区 API，反之亦然。
135
+ 首次安装会创建 `default` Profile。配置保存在 `~/.viceme-cli/config.json`，访问令牌仍只保存在操作系统密钥链中。不同 Profile 和区域的凭证彼此隔离。
135
136
 
136
- CLI 不提供公开的 API 地址、profile 或输出格式配置。本地开发时可以在终端环境中设置 `VICEME_API_BASE_URL`。
137
+ ```bash
138
+ viceme profile list
139
+ viceme profile add --name work --region global --use
140
+ viceme profile use default
141
+ viceme --profile work auth status
142
+ viceme profile rename work company
143
+ viceme profile remove company
144
+ ```
145
+
146
+ `profile use` 修改持久化的当前 Profile；全局 `--profile` 只覆盖本次命令。不要让 AI Agent 在用户没有明确要求时切换或删除 Profile。
147
+
148
+ 可以用 `VICEME_CLI_CONFIG_DIR` 覆盖配置根目录。本地 API 联调仍使用进程环境变量 `VICEME_API_BASE_URL`，不会写入 Profile。
149
+
150
+ 更新检查直接请求 npm registry，并且只把最近一次成功查询到的版本写入 `~/.viceme-cli/update-state.json`；registry 暂时不可用时，该结果最多回退使用 24 小时。`viceme install` 和 `viceme update` 启动的 npm 操作统一使用隔离的 `~/.viceme-cli/npm-cache`，不会因为用户级 `~/.npm` 缓存损坏而失败。这两个位置都不包含秘密信息，可以安全删除；凭证不会进入任何更新缓存。
137
151
 
138
152
  ## Agent Skills
139
153
 
@@ -160,10 +174,10 @@ viceme skills doctor
160
174
 
161
175
  | 命令 | 用途 |
162
176
  |---|---|
163
- | `viceme auth status` | 查看当前区域是否已认证 |
177
+ | `viceme auth status` | 查看当前 Profile 是否已认证 |
164
178
  | `viceme auth login --no-wait` | 启动设备授权并立即返回 |
165
179
  | `viceme auth login --device-code <code>` | 完成之前启动的设备授权 |
166
- | `viceme auth logout` | 撤销并删除当前区域的凭证 |
180
+ | `viceme auth logout` | 撤销并删除当前 Profile 的凭证 |
167
181
 
168
182
  令牌只保存在操作系统密钥链中，不会回退到明文存储；登录成功的输出也不会包含访问令牌或刷新令牌。
169
183
 
@@ -204,8 +218,9 @@ viceme skill publish --file ./poster-skill-v2.zip \
204
218
 
205
219
  | 命令组 | 用途 |
206
220
  |---|---|
207
- | `viceme install` | 安装持久化启动器、Agent Skill 和区域配置 |
221
+ | `viceme install` | 安装持久化启动器、Agent Skill 和默认 Profile |
208
222
  | `viceme auth` | 启动、完成、检查或撤销设备认证 |
223
+ | `viceme profile` | 新增、列出、切换、重命名或删除本地 Profile |
209
224
  | `viceme skill inspect` | 固化并检查来源候选，不执行发布 |
210
225
  | `viceme skill publish` | 创建或更新具有稳定链接的 Skill Agent 发布 |
211
226
  | `viceme skill target` | 解析现有逻辑 Agent Target 及其版本 |
@@ -266,7 +281,7 @@ CLI 执行错误写入 **stderr**，退出码非零：
266
281
  - **不执行来源内容** — CLI 和编译器不会执行第三方脚本、二进制文件、shell 片段、市场命令或复制口令中的指令。
267
282
  - **公开变更需要明确确认** — 发布和取消操作需要 `--yes`；退出码 `10` 表示 Agent 必须向用户取得确认，不能静默重试。
268
283
  - **安全预览** — 用户需要检查计划请求时，可以对 inspect 或 publish 使用 `--dry-run`，不会产生网络请求或发布副作用。
269
- - **凭证隔离** — 凭证保存在操作系统密钥链中，并按区域隔离。
284
+ - **凭证隔离** — 凭证保存在操作系统密钥链中，并按 Profile 与区域隔离。
270
285
  - **不可变输入** — inspect 会把发布绑定到不可变来源快照，而不是在之后重新读取浮动 URL。
271
286
  - **有界等待** — `job wait` 有最大等待时间；超时后返回最新持久化状态，不会取消工作流。
272
287
  - **可信分发** — npm 启动器从 GitHub 或 binary 镜像下载与其准确包版本匹配的二进制文件，并在启用前使用 npm 包内置的校验清单验证 SHA-256。
package/checksums.txt CHANGED
@@ -1,6 +1,6 @@
1
- d22d97438aa887b238ef6c506ccd19ffe049877754660d00e114069079ca2151 viceme_0.2.1_darwin_amd64
2
- 2157e6ccdbe76c6404e238fb2d04ea17c79289a1b712bfff42ddc8b1acdb7db6 viceme_0.2.1_darwin_arm64
3
- 96dc6b38b609639e3111bdbfcc9bf0bcedf3fa6a0c66e3b2b2d769261a6acc84 viceme_0.2.1_linux_amd64
4
- 7a9b0576ee36e9eab893f84669ca8cb6bd58d4bfc50a58054356c3863f710570 viceme_0.2.1_linux_arm64
5
- b825703ce462985bf8810b8c386e39b0e50ca6b600f301cec7a6822309e101b2 viceme_0.2.1_windows_amd64.exe
6
- cea8060b6f1f7f5a1c6bf44b787cd1ca5312c9b1f4e585b0f8bef325d6f748e0 viceme_0.2.1_windows_arm64.exe
1
+ bad1e762de8e1dee474e1704008a3341d85917072d499738ad14042af9b91ca4 viceme_0.3.1_darwin_amd64
2
+ 5d91b2ab59fd7d58e491f8500b7164a6a93ad310d5bdbbb7e974e7748721dc8e viceme_0.3.1_darwin_arm64
3
+ 10125de1ee952e5fe59f620900164ba577bce88cd260a4b81c842bc822d7923a viceme_0.3.1_linux_amd64
4
+ 4a9daf2223ca7a1a680ae83cdfbe0f02a96e0c660d9f508bb6d6d1f252d24099 viceme_0.3.1_linux_arm64
5
+ b9f70d30eaf89690e184e404e999ce5c649402797226f2dedb47aac5d44414e4 viceme_0.3.1_windows_amd64.exe
6
+ 35ee86d798a65fcf72725b47a092558af5462115f29fa25489868b0d86e27f56 viceme_0.3.1_windows_arm64.exe
package/docs/releasing.md CHANGED
@@ -9,7 +9,7 @@ files, create tags, write changelog entries, or run npm commands locally.
9
9
  1. Feature and fix PRs can merge into `dev` without starting release
10
10
  preparation.
11
11
  2. A maintainer explicitly opens or marks ready a repository-owned `dev` to
12
- `main` PR. That release intent starts `Prepare Release PR`.
12
+ `main` PR. That release intent starts `CLI release preparation`.
13
13
  3. `npm/scripts/prepare-release.mjs` finds the newest reachable stable tag and
14
14
  reads all unreleased non-merge commits.
15
15
  4. Conventional Commits select the next version:
@@ -26,7 +26,7 @@ files, create tags, write changelog entries, or run npm commands locally.
26
26
  checks, and is updated to `chore(release): vX.Y.Z` with exact run and commit
27
27
  evidence. No internal preparation PR is created.
28
28
  8. A maintainer reviews and merges that same Release PR.
29
- 9. `Release CLI and npm launcher` tags the exact reviewed `dev` head, reruns
29
+ 9. `CLI release publication` tags the exact reviewed `dev` head, reruns
30
30
  the quality gates, builds six platform binaries and six checksums, creates
31
31
  the GitHub Release, bundles those exact checksums into the npm launcher,
32
32
  publishes it, and then sends an
@@ -43,8 +43,9 @@ are not required. Configure:
43
43
  - repository secret `RELEASE_APP_PRIVATE_KEY`: the complete generated PEM key.
44
44
 
45
45
  Protect `dev` with an active branch ruleset that retains the normal pull request,
46
- one approving review, four CLI quality checks, deletion protection, and force
47
- push protection. Add `ViceMe CLI Release Bot` and the organization-admin role to
46
+ one approving review, the `PR quality` check, all three `PR npm installer
47
+ (<runner>)` checks, deletion protection, and force push protection. Add `ViceMe
48
+ CLI Release Bot` and the organization-admin role to
48
49
  the bypass list with `Always allow`; the latter preserves the legacy rule's
49
50
  existing `enforce_admins: false` behavior. Do not leave the legacy
50
51
  branch-protection rule active beside the ruleset because it cannot recognize the
@@ -56,12 +57,18 @@ when the job finishes. The workflow still stages an explicit allowlist of
56
57
  generated files and validates the complete release before pushing. No
57
58
  maintainer PAT or Deploy Key is used.
58
59
 
59
- The general CLI quality workflow runs for pull requests, not branch pushes. A
60
+ The general `CLI PR checks` workflow runs for pull requests, not branch pushes. A
60
61
  Release App push synchronizes the already-open `dev` to `main` PR, producing one
61
62
  set of required checks for the exact prepared commit without duplicate generic
62
63
  push and pull-request runs. The synchronize event may run release preparation a
63
64
  second time; that run is intentionally idempotent and produces no new commit.
64
65
 
66
+ Protect `main` with the same four PR checks plus `Release candidate
67
+ preparation`. The checks from `CLI release publication` are deliberately not
68
+ required for merging: that workflow starts only after the release PR has been
69
+ merged and performs the tag, binary, GitHub Release, npm, and notification
70
+ steps.
71
+
65
72
  Configure npm trusted publishing for:
66
73
 
67
74
  - npm package: `@viceme-ai/cli`;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@viceme-ai/cli",
3
- "version": "0.2.1",
3
+ "version": "0.3.1",
4
4
  "description": "Install and run the Viceme CLI and Viceme Agent Skill",
5
5
  "type": "module",
6
6
  "bin": {