clawhub/packages/clawhub-admin/README.md

ClawHub Admin CLI

Private operator CLI for ClawHub platform moderation and staff-only package operations.

This package is intentionally marked private: true. Do not publish it to npm. Run it from a checked-out ClawHub repo so maintainers always use the current repo code.

clawhub-admin reuses the public CLI's auth, config, HTTP, and schema helpers, but it is a separate maintainer command surface. Commands call the existing RBAC-gated entity endpoints, such as /api/v1/users/* and /api/v1/packages/*; there is no separate moderator API namespace.

Run

From the repo root:

bun install
bun run admin -- --help

Example:

bun run admin -- skills unhide maxhub-pipixia --reason "VT false positive; reanalysis clean" --yes

Build and Verify

bun run --cwd packages/clawhub-admin build
bun run --cwd packages/clawhub-admin verify

For full package coverage from the repo root:

bun run ci:packages

Local E2E

Use an isolated config path so admin testing never overwrites your normal clawhub CLI login:

export CLAWHUB_CONFIG_PATH=/tmp/clawhub-admin-local-config.json

Point --registry at the Convex HTTP actions URL, usually VITE_CONVEX_SITE_URL, not the Vite frontend URL:

bun run admin -- --registry http://127.0.0.1:3211 login --token <local-token> --no-browser
bun run admin -- --registry http://127.0.0.1:3211 whoami
bun run admin -- --registry http://127.0.0.1:3211 plugins queue --json

For a fresh anonymous local Convex deployment in a disposable worktree:

CONVEX_AGENT_MODE=anonymous bunx convex dev --local --typecheck=disable

In another shell, seed the local role fixture and use the returned admin token for admin commands:

CONVEX_AGENT_MODE=anonymous bunx convex run --no-push devSeed:seedCliRoleHelpFixtures

Commands

Authentication uses the same ClawHub token/config path as the public CLI:

bun run admin -- login
bun run admin -- whoami

User administration:

bun run admin -- users ban <handleOrId> [--id] [--fuzzy] [--reason <text>] [--yes]
bun run admin -- users unban <handleOrId> [--id] [--fuzzy] [--reason <text>] [--yes]
bun run admin -- users set-role <handleOrId> <user|moderator|admin> [--id] [--fuzzy] [--yes]
bun run admin -- users reclassify-ban <handleOrId> --reason <text> [--id] [--fuzzy] [--dry-run|--apply] [--yes] [--json]
bun run admin -- users remediate-autobans [--dry-run|--apply] [--user <handleOrId>] [--id] [--since <date>] [--limit <n>] [--cursor <cursor>] [--all] [--json]

Org publisher administration:

bun run admin -- org create <handle> --member <handle> [--display-name <name>] [--role owner|admin|publisher] [--trusted] [--json]
bun run admin -- org official list [--json]
bun run admin -- org official add <handle> --reason <text> [--yes] [--json]
bun run admin -- org official remove <handle> --reason <text> [--yes] [--json]

org create requires --member and defaults that member to owner; it does not add the admin running the command as an org member.

Package moderation and operations:

bun run admin -- skills reports [--status open|confirmed|dismissed|all]
bun run admin -- skills rescan <slug> [--version <version>] [--yes] [--json]
bun run admin -- skills unhide <slug> --reason <text> [--yes]
bun run admin -- skills triage-report <report-id> --status open|confirmed|dismissed [--note <text>] [--action none|hide] [--yes]

bun run admin -- plugins moderate <name> --version <version> --state approved|quarantined|revoked --reason <text>
bun run admin -- plugins status <name>
bun run admin -- plugins queue [--status open|blocked|manual|all]
bun run admin -- plugins reports [--status open|confirmed|dismissed|all]
bun run admin -- plugins triage-report <report-id> --status open|confirmed|dismissed [--note <text>] [--action none|quarantine|revoke] [--yes]

bun run admin -- plugins migrations [--phase <phase>]
bun run admin -- plugins set-migration <bundled-plugin-id> --package <name>
bun run admin -- plugins repair-name <name> --next-name <name> --reason <text> [--retire-target] [--owner <handle>] [--apply]
bun run admin -- plugins trusted-publisher get <name>
bun run admin -- plugins trusted-publisher set <name> --repository <owner/repo> --workflow-filename <file>
bun run admin -- plugins trusted-publisher delete <name>

All skill and plugin commands accept --json where the underlying endpoint supports machine-readable output.