CLI：p-user
CLI：p-user
Section titled “CLI：p-user”先读 CLI 总览：会话/目录、退出约定、角色边界、合成占位 ID 和执行授权规则在其中统一定义。本页逐叶补充例外；以下命令不是按顺序执行的脚本。
- viat p-user activate
- viat p-user assign-role
- viat p-user create
- viat p-user deactivate
- viat p-user delete
- viat p-user import
- viat p-user list
- viat p-user reset-mfa
- viat p-user set-admin
- viat p-user set-password
- viat p-user update
合成夹具与执行边界
Section titled “合成夹具与执行边界”这些文件只为下面例子提供输入；创建远程对象、执行脚本、数据库 SQL 或存储操作前，必须自行准备隔离项目并明确授权。生成文档不执行任何例子。
[{"identity":"demo_import_user","display_name":"Imported Demo"}]保存为 demo-users.json。demo_role 先通过 role create —name demo_role 创建；demo_user 是独立演示终端用户，不是平台登录邮箱。无密码行仅用于迁移形状，设置凭据后才能密码登录。
viat p-user activate
Section titled “viat p-user activate”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user activate <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: <IDENTITY> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["identity"],"id":"Activate","multiple":true,"required":false}
输入、行为与副作用。 启用已有项目终端用户 active 标记。不是许可证激活/平台登录/项目成员。
实际输出与退出。 stdout: <identity> is_active=true。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user activate demo_user失败处理、验证与清理。 identity 不存在失败；p-user list 验证。deactivate 可反转标记，不能撤销过去/进行中业务效果。
viat p-user assign-role
Section titled “viat p-user assign-role”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user assign-role [OPTIONS] <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: <IDENTITY> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
role: --role | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["identity","role"],"id":"AssignRole","multiple":true,"required":false}
输入、行为与副作用。 给已有 identity PUT 角色名；省略 —role 显式赋 null（取消分配），不是保留。
实际输出与退出。 stdout: assigned role -> <identity> (now role_id=<UUID-or->)。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user assign-role demo_user --role demo_role失败处理、验证与清理。 用户/角色不存在失败。保存原角色、list 核查、再赋原角色回退；取消分配不清用户自身 admin。
viat p-user create
Section titled “viat p-user create”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user create [OPTIONS] --identity <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
display_name: --display-name | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | — |
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: --identity | String, 1, Set | 是; Clap 无显式默认 | — | — |
password: --password | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | 冲突 ID：password_hash |
password_hash: --password-hash | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Instead of --password: an argon2 ($argon2id$…) or bcrypt ($2a$/$2b$/$2y$) hash from the system being migrated from |
role: --role | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["display_name","identity","password","password_hash","role"],"id":"Create","multiple":true,"required":false}
输入、行为与副作用。 创建项目终端用户 identity，可选显示名/角色及明文密码或导入 argon2/bcrypt hash（二者不同时）。不是平台协作者加入项目。
实际输出与退出。 stdout: created project user <identity>。不打印密码/hash、不登录新用户。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user create --identity demo_user --display-name 'Demo User' --role demo_role失败处理、验证与清理。 identity 重复、hash 错/密码过短（至少 8 字符）失败。真实凭据勿放 argv；批迁用受保护文件 import。p-user list 验证，delete demo_user 清理。
viat p-user deactivate
Section titled “viat p-user deactivate”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user deactivate <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: <IDENTITY> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["identity"],"id":"Deactivate","multiple":true,"required":false}
输入、行为与副作用。 停用已有项目终端用户 active 标记。不是许可证激活/平台登录/项目成员。
实际输出与退出。 stdout: <identity> is_active=false。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user deactivate demo_user失败处理、验证与清理。 identity 不存在失败；p-user list 验证。activate 可反转标记，不能撤销过去/进行中业务效果。
viat p-user delete
Section titled “viat p-user delete”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user delete <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: <IDENTITY> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["identity"],"id":"Delete","multiple":true,"required":false}
输入、行为与副作用。 删除项目终端用户身份，不是平台用户/协作者成员。可影响关联授权/凭据引用。
实际输出与退出。 stdout: deleted <identity>；成功 0。不撤销其先前业务写入。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user delete demo_user失败处理、验证与清理。 先盘点依赖，仅删演示用户。p-user list 核查；重建同 identity 不自动恢复旧 UUID/MFA/key/授权。
viat p-user import
Section titled “viat p-user import”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 demo-users.json 写 [{“identity”:“demo_import_user”,“display_name”:“Imported Demo”}]。此合成行无密码，设置前不可用于密码登录。
Usage: viat p-user import --file <FILE>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
file: --file | PathBuf, 1, Set | 是; Clap 无显式默认 | — | — |
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
Clap 参数组（literal metadata）：{"arguments":["file"],"id":"Import","multiple":true,"required":false}
输入、行为与副作用。 读 JSON 数组或 JSON Lines；每行 identity，可选 password/password_hash/display_name/email/phone/role/meta。每行拒绝未知字段。有效行逐 POST；失败继续，不是批事务。
实际输出与退出。 stdout 为 ok/FAILED #行及 <N> created, <N> failed。任一失败行在全部报告后退出 1；先前成功保留。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user import --file demo-users.json失败处理、验证与清理。 保护输入文件。重试前核对成功行，避免 identity 重复；清理仅删已创建演示身份。
viat p-user list
Section titled “viat p-user list”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user list [OPTIONS]命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
json: --json | bool, 0, SetTrue | 否；条件必填见行为; false | — | — |
Clap 参数组（literal metadata）：{"arguments":["json"],"id":"List","multiple":true,"required":false}
输入、行为与副作用。 读取 limit=500 一页，含 source/email。CLI 无分页/搜索参数；—json 仍是该页，不是全部。
实际输出与退出。 文本含 identity/source/role_id/显示名/邮箱/电话及 inactive 标记，附截断提示。—json 保留 page/total。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user list --json失败处理、验证与清理。 其余行用控制台/API ?q=&offset=&limit=。个人数据输出需保护；无变更/清理。
viat p-user reset-mfa
Section titled “viat p-user reset-mfa”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user reset-mfa <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: <IDENTITY> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["identity"],"id":"ResetMfa","multiple":true,"required":false}
输入、行为与副作用。 作为运维恢复 DELETE 终端用户二次验证，不重置平台账号 MFA。
实际输出与退出。 stdout 报告 cleared 或 had no two-factor authentication。项目策略可要求重新注册。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user reset-mfa demo_user失败处理、验证与清理。 先在带外确认身份。用户不存在失败；CLI 不可逆。用户需注册新验证器/恢复码，并验证下次授权登录遵循项目策略。
viat p-user set-admin
Section titled “viat p-user set-admin”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user set-admin --admin <ADMIN> <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
admin: --admin | bool, 1, Set | 是; Clap 无显式默认 | {"aliases":[],"help":null,"hidden":false,"name":"false"} / {"aliases":[],"help":null,"hidden":false,"name":"true"} | — |
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: <IDENTITY> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["admin","identity"],"id":"SetAdmin","multiple":true,"required":false}
输入、行为与副作用。 用 —admin true|false 设置用户自身 is_admin。所分配角色可独立授予 admin，故角色仍 admin 时仅设置 false 不等于完全降级。
实际输出与退出。 stdout: user <identity> admin=<bool>。改项目终端用户管理权限，不是平台权限。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user set-admin demo_user --admin false失败处理、验证与清理。 identity 不存在/布尔无效失败。检查自身标记与角色；需要时恢复旧布尔并查公开用户数据。
viat p-user set-password
Section titled “viat p-user set-password”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user set-password [OPTIONS] <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: <IDENTITY> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
password: --password | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | 冲突 ID：password_hash |
password_hash: --password-hash | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["identity","password","password_hash"],"id":"SetPassword","multiple":true,"required":false}
输入、行为与副作用。 以 —password/—password-hash 之一替换终端用户本地密码。导入 hash 支持 argon2/bcrypt；明文至少 8 字符。
实际输出与退出。 stdout: password set for <identity>。不暴露旧密码/hash。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user set-password demo_user --password demo-only-password失败处理、验证与清理。 无凭据/两种同时或 hash 无效失败。示例仅合成密码；真实 argv 可被进程/历史看到。经授权隔离登录核查；需恢复时用安全保管凭据，不能从输出推导旧值。
viat p-user update
Section titled “viat p-user update”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat p-user update [OPTIONS] <IDENTITY>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
display_name: --display-name | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | — |
email: --email | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | — |
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
identity: <IDENTITY> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
meta: --meta | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：A JSON object, replacing the stored meta whole |
phone: --phone | String, 1, Set | 否；条件必填见行为; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["display_name","email","identity","meta","phone"],"id":"Update","multiple":true,"required":false}
输入、行为与副作用。 PATCH 提供的 display-name/email/phone/meta；meta 解析 JSON。省略保留；空资料字符串按 API 清除/验证，不是通用 null 参数。
实际输出与退出。 stdout: updated <identity> display_name=… email=… phone=…。不改凭据/角色。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat p-user update demo_user --display-name 'Demo Renamed' --meta '{"demo":true}'失败处理、验证与清理。 JSON/邮箱/电话无效失败。电话可用常见符号及 5–20 位数字；校验邮箱形状。保存旧资料再逐字段恢复；list/API 验证。
实现核对依据
Section titled “实现核对依据”语法来自固定 Clap 合同与 main.rs；行为/权限核对以下源文件，路径相对产品仓库根。
crates/viat-cli/src/commands/project_user.rscrates/viat-api/src/handlers/project_users.rs