feat: add cocli docs

docs/developers/cocli/4-cli-user-role-registry.md

@@ -0,0 +1,93 @@
+---
+slug: user-role-registry
+sidebar_position: 4
+---
+
+# 用户、角色与容器镜像仓库
+
+本节介绍与组织成员、权限角色以及刻行容器镜像仓库相关的命令。这些能力通常用于管理员或需要在本地使用 Docker 拉取/推送镜像的场景。
+
+:::warning
+具体标志位与输出格式请以本机 `cocli user -h`、`cocli role -h`、`cocli registry -h` 及各子命令的 `-h` 为准。
+:::
+
+```bash
+cocli user -h
+cocli role -h
+cocli registry -h
+```
+
+## 用户 {#user}
+
+`cocli user` 用于查询当前登录身份所在组织（或指定项目）下的用户信息。
+
+### 列举用户 {#user-list}
+
+- **不传 `-p`**：按**组织**范围列举用户。
+- **传入 `-p <项目 slug>`**：仅列举该项目下的用户。
+- **`--role-code`**：按角色代码过滤（例如 `PROJECT_WRITER`、`ORGANIZATION_ADMIN`）。可与 `cocli role list` 中看到的角色编码对照使用。
+- **分页**：与 `record list` 类似，使用 `--page-size`（10–100）与 `--page-token` 翻页；默认每页条数由服务端上限决定，终端会在有下一页时提示 `--page-token`。
+- **输出**：`-o` 支持 `table`、`wide`、`json`、`yaml`；`-v` 为更详细的表格列。
+
+```bash
+# 组织内用户
+cocli user list
+
+# 某项目内用户
+cocli user list -p my-project-slug
+
+# 按角色过滤（示例）
+cocli user list --role-code PROJECT_WRITER -o json
+```
+
+### 查看用户详情 {#user-get}
+
+- **无参数**：尝试获取**当前登录用户**（若接口不可用，请显式传入用户 ID 或资源名）。
+- **有参数**：支持用户 **ID**（将解析为 `users/<id>`）或完整资源名（如 `users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）。
+
+```bash
+cocli user get
+cocli user get <user-id>
+cocli user get users/<uuid> -o json
+```
+
+## 角色 {#role}
+
+`cocli role list` 列出平台中可用的角色定义，便于与 `cocli user list --role-code` 配合使用。
+
+- **`--level`**：可选 `organization` 或 `project`，只看待定层级的角色。
+- **分页**：`--page-size`、`--page-token`，行为与 `user list` 一致。
+- **输出**：`-o table|wide|json|yaml`，`-v` 更详细。
+
+```bash
+cocli role list
+cocli role list --level project -o wide
+```
+
+## 容器镜像仓库 {#registry}
+
+`cocli registry` 用于获取刻行容器镜像仓库的临时凭证，并可选地调用本机 **Docker** 执行 `docker login`。子命令**不走与普通资源命令相同的全局登录校验**，但仍需本地配置文件中存在可用的登录配置，以便调用 OpenAPI 签发凭证。
+
+### 登录 Docker（推荐） {#registry-login}
+
+根据当前 profile 的 **OpenAPI endpoint** 推断镜像仓库域名（例如 SaaS `openapi.coscene.cn` 对应 `cr.coscene.cn`）；若无法推断，需使用 **`--registry`** 手动指定主机名。
+
+**要求**：本机已安装 Docker，且 `docker` 在 `PATH` 中。
+
+```bash
+cocli registry login
+cocli registry login --registry cr.example.com
+```
+
+### 仅生成临时凭证 {#registry-create-credential}
+
+不调用 Docker，仅向标准输出打印用户名与密码（临时凭证）。默认纯文本两行；也可使用 `-o json` / `yaml` / `table` 便于脚本解析。
+
+```bash
+cocli registry create-credential
+cocli registry create-credential -o json
+```
+
+:::tip
+临时密码请视为敏感信息，勿写入版本库或日志；在 CI 中优先使用密钥管理或短期令牌策略。
+:::

i18n/en/docusaurus-plugin-content-docs/current/developers/cocli/4-cli-user-role-registry.md

@@ -0,0 +1,93 @@
+---
+slug: user-role-registry
+sidebar_position: 4
+---
+
+# Users, Roles, and Container Registry
+
+This page covers commands for organization members, role definitions, and the coScene container registry. They are typically used by administrators or anyone who needs to pull/push images with Docker locally.
+
+:::warning
+For exact flags and output formats, run `cocli user -h`, `cocli role -h`, `cocli registry -h`, and `-h` on each subcommand on your machine.
+:::
+
+```bash
+cocli user -h
+cocli role -h
+cocli registry -h
+```
+
+## Users {#user}
+
+`cocli user` queries users in the organization (or a specific project) for the currently logged-in identity.
+
+### List users {#user-list}
+
+- **Without `-p`**: list users at the **organization** scope.
+- **With `-p <project slug>`**: list users in that project only.
+- **`--role-code`**: filter by role code (e.g. `PROJECT_WRITER`, `ORGANIZATION_ADMIN`). Cross-check codes with `cocli role list`.
+- **Pagination**: use `--page-size` (10–100) and `--page-token`, similar to `record list`; the CLI prints a suggested `--page-token` when more pages exist.
+- **Output**: `-o` supports `table`, `wide`, `json`, and `yaml`; `-v` enables more columns.
+
+```bash
+# Organization users
+cocli user list
+
+# Users in a project
+cocli user list -p my-project-slug
+
+# Filter by role (example)
+cocli user list --role-code PROJECT_WRITER -o json
+```
+
+### Get user details {#user-get}
+
+- **No argument**: fetch the **current authenticated user** (if that fails, pass a user ID or resource name explicitly).
+- **With argument**: accepts a user **ID** (resolved to `users/<id>`) or a full resource name such as `users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
+
+```bash
+cocli user get
+cocli user get <user-id>
+cocli user get users/<uuid> -o json
+```
+
+## Roles {#role}
+
+`cocli role list` lists available role definitions, useful together with `cocli user list --role-code`.
+
+- **`--level`**: optional `organization` or `project` to restrict the level.
+- **Pagination**: `--page-size` and `--page-token`, same idea as `user list`.
+- **Output**: `-o table|wide|json|yaml`, `-v` for more detail.
+
+```bash
+cocli role list
+cocli role list --level project -o wide
+```
+
+## Container registry {#registry}
+
+`cocli registry` obtains short-lived credentials for the coScene container registry and can invoke local **Docker** to run `docker login`. These subcommands use a different auth gate than most resource commands, but you still need a valid profile in your config file so the OpenAPI client can issue credentials.
+
+### Docker login (recommended) {#registry-login}
+
+The registry host is inferred from the profile **OpenAPI endpoint** (e.g. SaaS `openapi.coscene.cn` → `cr.coscene.cn`). If inference fails, pass **`--registry`** with the hostname.
+
+**Requires**: Docker installed and `docker` on your `PATH`.
+
+```bash
+cocli registry login
+cocli registry login --registry cr.example.com
+```
+
+### Print credentials only {#registry-create-credential}
+
+Does not call Docker; prints username and password (temporary credential) to stdout. Default is plain text; use `-o json`, `yaml`, or `table` for scripting.
+
+```bash
+cocli registry create-credential
+cocli registry create-credential -o json
+```
+
+:::tip
+Treat temporary passwords as secrets—do not commit them or log them. In CI, prefer a secret store or short-lived tokens.
+:::