Agent Skills
› ahaodev/shadmin
› shadmin-cli
shadmin-cli
GitHub提供通过终端查询 Shadmin 管理平台资源（用户、角色、菜单、API）的能力。该技能封装只读 CLI，支持 OAuth 认证与 RBAC 权限继承，适用于列表查看、详情获取及 API 端点查询等只读场景。
触发场景
查询管理员平台用户信息
查看系统角色或菜单结构
获取已注册的 API 端点列表
安装
npx skills add ahaodev/shadmin --skill shadmin-cli -g -y
SKILL.md
Frontmatter
{
"name": "shadmin-cli",
"description": "Use this skill when the user asks to query Shadmin admin platform resources\n(users, roles, menus, registered API resources) from a terminal — for example\n\"list shadmin users\", \"show shadmin role detail\", \"dump shadmin menu tree\",\n\"what API endpoints does shadmin expose\". The skill calls the `shadmin-cli`\nbinary, which wraps the Shadmin REST API and inherits the logged-in user's\nRBAC permissions. Do NOT use this skill for write operations (create \/ update\n\/ delete) — the MVP exposes read-only commands only."
}
shadmin-cli skill
shadmin-cli is a thin Go CLI on top of the Shadmin REST API. It is designed
to be driven by external AI agents.
- Authentication: OAuth device authorization flow → JWT cached locally in
cli/.envor theSHADMIN_CONFIGpath (mode 0600). - Authorization: every request reuses the logged-in user's existing RBAC. The CLI cannot bypass server-side permission checks.
- Output: JSON by default (stable, machine-readable). Pass
--prettyfor human-readable tables. - Exit codes:
0ok ·1generic ·2usage ·3network ·4unauthenticated / token expired ·5permission denied (403) ·6not found ·7server error.
Prerequisites
- The
shadmin-clibinary is on$PATH. - The user has run
shadmin-cli loginat least once on this machine.- To check: run
shadmin-cli whoami. Exit code4means not logged in.
- To check: run
- The Shadmin server is reachable (default
http://localhost:55667).
If the user is not logged in, ask for the server URL, then run:
shadmin-cli login --server <URL>
# Open the printed URL in a browser and enter the displayed user code.
Command reference (MVP, read-only)
| Command | Purpose |
|---|---|
shadmin-cli login [--server URL] |
Cache JWT locally via device auth |
shadmin-cli logout |
Clear local tokens |
shadmin-cli whoami |
Current user profile |
shadmin-cli users list [--page --page-size --keyword] |
List users (paginated) |
shadmin-cli users get <id> |
Get user by id |
shadmin-cli roles list |
List roles |
shadmin-cli roles get <id> |
Get role by id |
shadmin-cli menus tree |
Menu tree (UI nav structure) |
shadmin-cli menus list |
Flat menu list |
shadmin-cli menus get <id> |
Get menu by id |
shadmin-cli api-resources list |
All API endpoints registered by backend |
Global flags:
--server URLoverrides the saved server URL for this invocation.--prettyswitches output format. JSON is the default.SHADMIN_SERVERoverrides the saved server URL for this invocation.- CLI env examples live under
cli/(.env.example); backend root.envfiles should not contain CLI-only settings. cli/.envis generated byshadmin-cli loginas the local token cache.
Response envelope
The CLI strips Shadmin's {code, msg, data} envelope and prints the inner
data directly. List endpoints return either:
{ "list": [...], "total": N, "page": N, "page_size": N, "total_pages": N }
…or a plain array (e.g. roles list). api-resources list uses items instead
of list. Inspect the JSON shape before parsing.
Error handling guidance
- Exit 4 → token expired or missing. Ask the user to re-run
shadmin-cli loginand retry. - Exit 5 → the logged-in user lacks RBAC permission for that API. Do not retry; report the permission gap to the user.
- Exit 3 → network failure. Verify the server URL and retry once.
- Exit 6 → the requested id does not exist. Surface the error verbatim.
Safety
- Write operations (
create / update / delete) are NOT exposed in this MVP. If the user asks for one, refuse and explain. - The CLI uses the same permissions as the logged-in user. Do not assume an agent context implies elevated access.
Examples
See examples/ for real JSON outputs from each MVP command.
版本历史
- 69286ec 当前 2026-07-25 09:47
