LLMSkillHub
mirroredCopied from ahaodev/shadmin under MIT. ahaodev has not claimed this page, and is not affiliated with LLM SkillHub.

ahaodev / shadmin-cli

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.

0
SKILL.md
4.3 KB

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

  1. The shadmin-cli binary is on $PATH.

  2. 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.
  3. 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)

CommandPurpose
shadmin-cli login [--server URL]Cache JWT locally via device auth
shadmin-cli logoutClear local tokens
shadmin-cli whoamiCurrent 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 listList roles
shadmin-cli roles get <id>Get role by id
shadmin-cli menus treeMenu tree (UI nav structure)
shadmin-cli menus listFlat menu list
shadmin-cli menus get <id>Get menu by id
shadmin-cli api-resources listAll 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.