| name | shadmin-cli |
| description | Use this skill when the user asks to query Shadmin admin platform resources
(users, roles, menus, registered API resources) from a terminal — for example
"list shadmin users", "show shadmin role detail", "dump shadmin menu tree",
"what API endpoints does shadmin expose". The skill calls the `shadmin-cli`
binary, which wraps the Shadmin REST API and inherits the logged-in user's
RBAC permissions. Do NOT use this skill for write operations (create / update
/ 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>
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.
Examples
See examples/ for real JSON outputs from each MVP command.
