Agent Skills › ahaodev/shadmin › shadmin-cli

shadmin-cli

GitHub

用于通过终端查询 Shadmin 平台资源（用户、角色、菜单、API），支持只读操作。基于 Go CLI 封装 REST API，继承 RBAC 权限，输出 JSON。

cli/skill/shadmin-cli/SKILL.md ahaodev/shadmin

Trigger Scenarios

查询管理员平台用户列表或详情查看角色信息或菜单树结构获取注册的 API 端点列表

Install

npx skills add ahaodev/shadmin --skill shadmin-cli -g -y

More Options

Non-standard path

npx skills add https://github.com/ahaodev/shadmin/tree/main/cli/skill/shadmin-cli -g -y

Use without installing

npx skills use ahaodev/shadmin@shadmin-cli

指定 Agent (Claude Code)

npx skills add ahaodev/shadmin --skill shadmin-cli -a claude-code -g -y

安装 repo 全部 skill

npx skills add ahaodev/shadmin --all -g -y

预览 repo 内 skill

npx skills add ahaodev/shadmin --list

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/.env or the SHADMIN_CONFIG path (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 --pretty for human-readable tables.
Exit codes: 0 ok · 1 generic · 2 usage · 3 network · 4 unauthenticated / token expired · 5 permission denied (403) · 6 not found · 7 server error.

Prerequisites

The shadmin-cli binary is on $PATH.
The user has run shadmin-cli login at least once on this machine.
- To check: run shadmin-cli whoami. Exit code 4 means not logged in.
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 URL overrides the saved server URL for this invocation.
--pretty switches output format. JSON is the default.
SHADMIN_SERVER overrides the saved server URL for this invocation.
CLI env examples live under cli/ (.env.example); backend root .env files should not contain CLI-only settings.
cli/.env is generated by shadmin-cli login as 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 login and 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.