cli.md

summary	CLI reference: commands, flags, config, lockfile, sync behavior.
read_when	Working on CLI behavior Debugging install/update/sync

CLI

CLI package: packages/clawhub/ (published as clawhub, bin: clawhub).

From this repo you can run it via the wrapper script:

bun clawhub --help

Global flags

• --workdir <dir>: working directory (default: cwd; falls back to Clawdbot workspace if configured)
• --dir <dir>: install dir under workdir (default: skills)
• --site <url>: base URL for browser login (default: https://clawhub.ai)
• --registry <url>: API base URL (default: discovered, else https://clawhub.ai)
• --no-input: disable prompts

Env equivalents:

• CLAWHUB_SITE (legacy CLAWDHUB_SITE)
• CLAWHUB_REGISTRY (legacy CLAWDHUB_REGISTRY)
• CLAWHUB_WORKDIR (legacy CLAWDHUB_WORKDIR)

HTTP proxy

The CLI respects standard HTTP proxy environment variables for systems behind corporate proxies or restricted networks:

• HTTPS_PROXY / https_proxy
• HTTP_PROXY / http_proxy
• NO_PROXY / no_proxy

When any of these variables is set, the CLI routes outbound requests through the specified proxy. HTTPS_PROXY is used for HTTPS requests, HTTP_PROXY for plain HTTP. NO_PROXY / no_proxy is respected to bypass the proxy for specific hosts or domains.

This is required on systems where direct outbound connections are blocked (e.g. Docker containers, Hetzner VPS with proxy-only internet, corporate firewalls).

Example:

export HTTPS_PROXY=http://proxy.example.com:3128
export NO_PROXY=localhost,127.0.0.1
clawhub search "my query"

When no proxy variable is set, behavior is unchanged (direct connections).

Config file

Stores your API token + cached registry URL.

• macOS: ~/Library/Application Support/clawhub/config.json
• Linux/XDG: $XDG_CONFIG_HOME/clawhub/config.json or ~/.config/clawhub/config.json
• Windows: %APPDATA%\\clawhub\\config.json
• Legacy fallback: if clawhub/config.json does not exist yet but clawdhub/config.json does, the CLI reuses the legacy path
• override: CLAWHUB_CONFIG_PATH (legacy CLAWDHUB_CONFIG_PATH)

Commands

login / auth login

• Default: opens browser to <site>/cli/auth and completes via loopback callback.
• Headless: clawhub login --token clh_...

whoami

• Verifies the stored token via /api/v1/whoami.

star <slug> / unstar <slug>

• Adds/removes a skill from your highlights.
• Calls POST /api/v1/stars/<slug> and DELETE /api/v1/stars/<slug>.
• --yes skips confirmation.

search <query...>

• Calls /api/v1/search?q=....
• Search favors exact slug/name token matches before download popularity. A standalone slug token such as map matches personal-map more strongly than the substring inside amap.
• Downloads are a small popularity prior, not a guarantee of top placement.
• If a skill should appear but does not, run clawhub inspect <slug> while logged in to check owner-visible moderation diagnostics before renaming metadata.

explore

• Lists newest skills via /api/v1/skills?limit=...&sort=createdAt (sorted by createdAt desc).
• Flags:
  • --limit <n> (1-200, default: 25)
  • --sort newest|updated|downloads|rating|installs|installsAllTime|trending (default: newest)
  • --json (machine-readable output)
• Output: <slug> v<version> <age> <summary> (summary truncated to 50 chars).

inspect <slug>

• Fetches skill metadata and version files without installing.
• --version <version>: inspect a specific version (default: latest).
• --tag <tag>: inspect a tagged version (e.g. latest).
• --versions: list version history (first page).
• --limit <n>: max versions to list (1-200).
• --files: list files for the selected version.
• --file <path>: fetch raw file content (text files only; 200KB limit).
• --json: machine-readable output.

install <slug>

• Resolves latest version via /api/v1/skills/<slug>.
• Downloads zip via /api/v1/download.
• Extracts into <workdir>/<dir>/<slug>.
• Writes:
  • <workdir>/.clawhub/lock.json (legacy .clawdhub)
  • <skill>/.clawhub/origin.json (legacy .clawdhub)

uninstall <slug>

• Removes <workdir>/<dir>/<slug> and deletes the lockfile entry.
• Interactive: asks for confirmation.
• Non-interactive (--no-input): requires --yes.

list

• Reads <workdir>/.clawhub/lock.json (legacy .clawdhub).

update [slug] / update --all

• Computes fingerprint from local files.
• If fingerprint matches a known version: no prompt.
• If fingerprint does not match:
  • refuses by default
  • overwrites with --force (or prompt, if interactive)

skill publish <path>

• Publishes via POST /api/v1/skills (multipart).
• Requires semver: --version 1.2.3.
• Publishing a skill means it is released under MIT-0 on ClawHub.
• Published skills are free to use, modify, and redistribute without attribution.
• ClawHub does not support paid skills or per-skill pricing.
• Legacy alias: publish <path>.

delete <slug>

• Soft-delete a skill (owner, moderator, or admin).
• Calls DELETE /api/v1/skills/{slug}.
• --reason <text> records a moderation note on the skill and audit log.
• --note <text> is an alias for --reason.
• --yes skips confirmation.

undelete <slug>

• Restore a hidden skill (owner, moderator, or admin).
• Calls POST /api/v1/skills/{slug}/undelete.
• --reason <text> records a moderation note on the skill and audit log.
• --note <text> is an alias for --reason.
• --yes skips confirmation.

hide <slug>

• Hide a skill (owner, moderator, or admin).
• Alias for delete.

unhide <slug>

• Unhide a skill (owner, moderator, or admin).
• Alias for undelete.

skill rename <slug> <new-slug>

• Rename an owned skill and keep the previous slug as a redirect alias.
• Calls POST /api/v1/skills/{slug}/rename.
• --yes skips confirmation.

skill merge <source-slug> <target-slug>

• Merge one owned skill into another owned skill.
• The source slug stops listing publicly and becomes a redirect alias to the target.
• Calls POST /api/v1/skills/{sourceSlug}/merge.
• --yes skips confirmation.

transfer

• Ownership transfer workflow.
• Subcommands:
  • transfer request <slug> <handle> [--message "..."] [--yes]
  • transfer list [--outgoing]
  • transfer accept <slug> [--yes]
  • transfer reject <slug> [--yes]
  • transfer cancel <slug> [--yes]
• Endpoints:
  • POST /api/v1/skills/{slug}/transfer
  • POST /api/v1/skills/{slug}/transfer/accept
  • POST /api/v1/skills/{slug}/transfer/reject
  • POST /api/v1/skills/{slug}/transfer/cancel
  • GET /api/v1/transfers/incoming
  • GET /api/v1/transfers/outgoing

ban-user <handleOrId>

• Ban a user and delete owned skills (moderator/admin only).
• Calls POST /api/v1/users/ban.
• --id treats the argument as a user id instead of a handle.
• --fuzzy resolves the handle via fuzzy user search (admin only).
• --reason records an optional ban reason.
• --yes skips confirmation.

unban-user <handleOrId>

• Unban a user and restore eligible skills (admin only).
• Calls POST /api/v1/users/unban.
• --id treats the argument as a user id instead of a handle.
• --fuzzy resolves the handle via fuzzy user search (admin only).
• --reason records an optional unban reason.
• --yes skips confirmation.

set-role <handleOrId> <role>

• Change a user role (admin only).
• Calls POST /api/v1/users/role.
• --id treats the argument as a user id instead of a handle.
• --fuzzy resolves the handle via fuzzy user search (admin only).
• --yes skips confirmation.

package explore [query...]

• Browses or searches the unified package catalog via GET /api/v1/packages and GET /api/v1/packages/search.
• Use this for plugins and other package-family entries; top-level search remains the skill search surface.
• Flags:
  • --family skill|code-plugin|bundle-plugin
  • --official
  • --executes-code
  • --target <target>, --os <os>, --arch <arch>, --libc <libc>
  • --requires-browser, --requires-desktop, --requires-native-deps
  • --requires-external-service, --external-service <name>
  • --binary <name>, --os-permission <name>
  • --artifact-kind legacy-zip|npm-pack
  • --npm-mirror
  • --limit <n> (1-100, default: 25)
  • --json

Examples:

clawhub package explore --family code-plugin
clawhub package explore --family code-plugin --os darwin --requires-desktop
clawhub package explore --family code-plugin --artifact-kind npm-pack
clawhub package explore --npm-mirror
clawhub package explore episodic-claw --family code-plugin

package inspect <name>

• Fetches package metadata without installing.
• Use this for plugin metadata, compatibility, verification, source, and version/file inspection.
• --version <version>: inspect a specific version (default: latest).
• --tag <tag>: inspect a tagged version (e.g. latest).
• --versions: list version history (first page).
• --limit <n>: max versions to list (1-100).
• --files: list files for the selected version.
• --file <path>: fetch raw file content (text files only; 200KB limit).
• --json: machine-readable output.

package download <name>

• Resolves a package version through GET /api/v1/packages/{name}/versions/{version}/artifact.
• Downloads the artifact from the resolver's downloadUrl.
• Verifies ClawHub SHA-256 for all artifacts.
• For ClawPack npm-pack artifacts, also verifies npm sha512 integrity, npm shasum, and the tarball's package.json name/version.
• Legacy ZIP versions download through the legacy ZIP route.
• Flags:
  • --version <version>: download a specific version.
  • --tag <tag>: download a tagged version (default: latest).
  • -o, --output <path>: output file or directory.
  • --force: overwrite an existing output file.
  • --json: machine-readable output.

Examples:

clawhub package download @openclaw/example-plugin --tag latest
clawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/

package verify <file>

• Computes ClawHub SHA-256, npm sha512 integrity, and npm shasum for a local artifact.
• With --package, resolves expected metadata from ClawHub and compares the local file against the published artifact metadata.
• With direct digest flags, verifies without a network lookup.
• Flags:
  • --package <name>: package name to resolve expected artifact metadata.
  • --version <version> or --tag <tag>: expected package version.
  • --sha256 <hex>: expected ClawHub SHA-256.
  • --npm-integrity <sri>: expected npm integrity.
  • --npm-shasum <sha1>: expected npm shasum.
  • --json: machine-readable output.

Examples:

clawhub package verify ./example-plugin-1.2.3.tgz --package @openclaw/example-plugin --version 1.2.3
clawhub package verify ./example-plugin-1.2.3.tgz --sha256 <hex>

package moderate <name>

• Moderator/admin command for package release review.
• Calls POST /api/v1/packages/{name}/versions/{version}/moderation.
• approved allows a release after review.
• quarantined and revoked block artifact downloads.
• Flags:
  • --version <version>: required release version.
  • --state approved|quarantined|revoked: required moderation state.
  • --reason <text>: required audit note.
  • --json: machine-readable output.

Example:

clawhub package moderate @openclaw/example-plugin --version 1.2.3 --state quarantined --reason "suspicious native payload"

package report

• Authenticated command for reporting a package to moderators.
• Calls POST /api/v1/packages/{name}/report.
• Reports are package-level, optionally tied to a version, and feed package moderation-queue.
• Reports do not auto-hide packages or block downloads by themselves.
• Flags:
  • --version <version>: optional package version to attach to the report.
  • --reason <text>: required report reason.
  • --json: machine-readable output.

Example:

clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "suspicious native payload"

package appeal

• Owner/publisher command for appealing release moderation.
• Calls POST /api/v1/packages/{name}/appeal.
• Appeals are accepted for quarantined, revoked, suspicious, or malicious releases.
• Flags:
  • --version <version>: required package version.
  • --message <text>: required appeal message.
  • --json: machine-readable output.

Example:

clawhub package appeal @openclaw/example-plugin --version 1.2.3 --message "linked source release explains the native binary"

package appeals

• Moderator/admin command for listing package appeals.
• Calls GET /api/v1/packages/appeals.
• Flags:
  • --status open|accepted|rejected|all: appeal state filter, default open.
  • --cursor <cursor>: resume cursor from a previous page.
  • --limit <n>: number of appeals to show, max 100.
  • --json: machine-readable output.

Examples:

clawhub package appeals
clawhub package appeals --status all --limit 50

package resolve-appeal

• Moderator/admin command for accepting, rejecting, or reopening a package appeal.
• Calls POST /api/v1/packages/appeals/{appealId}/resolve.
• Resolving an appeal does not automatically change release moderation state; use package moderate to approve, quarantine, or revoke the artifact.
• Flags:
  • --status open|accepted|rejected: required appeal state.
  • --note <text>: required unless --status open.
  • --json: machine-readable output.

Example:

clawhub package resolve-appeal packageAppeals:abc --status rejected --note "static finding still applies"

package reports

• Moderator/admin command for listing package reports.
• Calls GET /api/v1/packages/reports.
• Flags:
  • --status open|triaged|dismissed|all: report state filter, default open.
  • --cursor <cursor>: resume cursor from a previous page.
  • --limit <n>: number of reports to show, max 100.
  • --json: machine-readable output.

Examples:

clawhub package reports
clawhub package reports --status all --limit 50

package triage-report

• Moderator/admin command for resolving or reopening package reports.
• Calls POST /api/v1/packages/reports/{reportId}/triage.
• Flags:
  • --status open|triaged|dismissed: required report state.
  • --note <text>: required unless --status open.
  • --json: machine-readable output.

Example:

clawhub package triage-report packageReports:abc --status triaged --note "quarantined affected release"

package moderation-status

• Owner/staff command for checking package moderation visibility.
• Calls GET /api/v1/packages/{name}/moderation.
• Shows current package scan state, open report count, latest release manual moderation state, download block state, and moderation reasons.
• Flags:
  • --json: machine-readable output.

Example:

clawhub package moderation-status @openclaw/example-plugin

package moderation-queue

• Moderator/admin command for reviewing package releases that need attention.
• Calls GET /api/v1/packages/moderation/queue.
• Does not change release state; use package moderate for approve, quarantine, or revoke actions.
• Flags:
  • --status open|blocked|manual|all: queue filter, default open.
  • --cursor <cursor>: resume cursor from a previous page.
  • --limit <n>: number of releases to show, max 100.
  • --json: machine-readable output.

Examples:

clawhub package moderation-queue
clawhub package moderation-queue --status blocked --limit 50

package backfill-artifacts

• Admin command for labeling older package releases with explicit artifact-kind metadata.
• Calls POST /api/v1/packages/backfill/artifacts.
• Defaults to dry-run. Pass --apply to write changes.
• Labels releases without ClawPack storage as legacy-zip; releases that already have ClawPack storage are repaired as npm-pack.
• Flags:
  • --batch-size <n>: number of releases to scan, max 500.
  • --cursor <cursor>: resume cursor from a previous run.
  • --all: continue until the backfill is done.
  • --apply: write changes instead of dry-run.
  • --json: machine-readable output.

Examples:

clawhub package backfill-artifacts --batch-size 100
clawhub package backfill-artifacts --all --apply

package readiness <name>

• Checks whether a package is ready for future OpenClaw consumption.
• Calls GET /api/v1/packages/{name}/readiness.
• Reports blockers for official status, ClawPack availability, artifact digest, source provenance, OpenClaw compatibility, host targets, environment metadata, and scan state.
• Flags:
  • --json: machine-readable output.

Example:

clawhub package readiness @openclaw/example-plugin

package migration-status <name>

• Shows operator-oriented migration status for a package that may replace a bundled OpenClaw plugin.
• Calls the same computed readiness endpoint as package readiness, but prints migration-focused status, latest version, official-package state, checks, and blockers.
• Flags:
  • --json: machine-readable output.

Example:

clawhub package migration-status @openclaw/example-plugin

package migrations

• Staff command for listing durable official plugin migration rows.
• Calls GET /api/v1/packages/migrations.
• Flags:
  • --phase planned|published|clawpack-ready|legacy-zip-only|metadata-ready|blocked|ready-for-openclaw|all: phase filter, default all.
  • --cursor <cursor>: resume cursor from a previous page.
  • --limit <n>: number of migrations to show, max 100.
  • --json: machine-readable output.

Examples:

clawhub package migrations
clawhub package migrations --phase blocked --limit 50

package set-migration

• Admin command for creating or updating an official plugin migration row.
• Calls POST /api/v1/packages/migrations.
• Tracks the mapping from an old bundled OpenClaw plugin id to its future ClawHub package, source location, phase, blockers, and readiness flags.
• Flags:
  • --package <name>: required ClawHub package name.
  • --owner <owner>: operator/team owner.
  • --source-repo <repo>: source repository.
  • --source-path <path>: source path inside the repository.
  • --source-commit <sha>: source commit SHA.
  • --phase <phase>: planned, published, clawpack-ready, legacy-zip-only, metadata-ready, blocked, or ready-for-openclaw.
  • --blockers <items>: comma-separated blockers.
  • --host-targets-complete: mark host target metadata complete.
  • --scan-clean: mark scan state clean.
  • --moderation-approved: mark moderation approved.
  • --runtime-bundles-ready: mark runtime bundles ready.
  • --notes <text>: operator notes.
  • --json: machine-readable output.

Example:

clawhub package set-migration core.search --package @openclaw/search-plugin --phase blocked --blockers "missing ClawPack"

package publish <source>

• Publishes a code plugin or bundle plugin via POST /api/v1/packages.
• <source> accepts:
  • Local folder path: ./my-plugin
  • Local ClawPack npm-pack tarball: ./my-plugin-1.2.3.tgz
  • GitHub repo: owner/repo or owner/repo@ref
  • GitHub URL: https://github.com/owner/repo
• Metadata is auto-detected from package.json, openclaw.plugin.json, and real OpenClaw bundle markers such as .codex-plugin/plugin.json, .claude-plugin/plugin.json, and .cursor-plugin/plugin.json.
• .tgz sources are treated as ClawPack. The CLI uploads the exact npm-pack bytes and uses the extracted package/ contents only for validation and metadata prefill.
• Code-plugin folders are packed into a ClawPack npm tarball before upload so OpenClaw installs can verify the exact artifact. Bundle-plugin folders still use the extracted-file publish path.
• For GitHub sources, source attribution is auto-populated from the repo, resolved commit, ref, and subpath.
• For local folders, source attribution is auto-detected from local git when the origin remote points at GitHub.
• External code plugins must declare openclaw.compat.pluginApi and openclaw.build.openclawVersion explicitly. Top-level package.json.version is not used as a fallback for publish validation.
• --dry-run previews the resolved publish payload without uploading.
• --json emits machine-readable output for CI.
• --owner <handle> lets admins publish under a shared owner account while keeping their own token as the actor.
• Existing flags (--family, --name, --version, --source-repo, --source-commit, --source-ref, --source-path) still work as overrides.
• Private GitHub repos require GITHUB_TOKEN.

Recommended local flow

Use --dry-run first so you can confirm the resolved package metadata and source attribution before creating a live release:

npm pack
clawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-run
clawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin

Local folder flow

For code plugins, folder publish builds and uploads a ClawPack artifact from the package folder:

clawhub package publish ./my-plugin --family code-plugin --dry-run
clawhub package publish ./my-plugin --family code-plugin

Minimal package.json for --family code-plugin

External code plugins need a small amount of OpenClaw metadata in package.json. This minimal manifest is enough for a successful publish:

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2"
    }
  }
}

Required fields:

• openclaw.compat.pluginApi
• openclaw.build.openclawVersion

Notes:

• package.json.version is your package release version, but it is not used as a fallback for OpenClaw compatibility/build validation.
• openclaw.hostTargets and openclaw.environment are optional metadata. ClawHub may surface them when present, but they are not required for publish.
• openclaw.compat.minGatewayVersion and openclaw.build.pluginSdkVersion are optional extras if you want to publish more detailed compatibility metadata.
• If you are using an older clawhub CLI release, upgrade before publishing so the local preflight checks run before upload.

GitHub Actions

ClawHub also ships an official reusable workflow at /.github/workflows/package-publish.yml for plugin repos.

Typical caller setup:

name: Package Publish

on:
  pull_request:
  workflow_dispatch:
  push:
    tags:
      - "v*"

jobs:
  dry-run:
    if: github.event_name == 'pull_request'
    uses: openclaw/clawhub/.github/workflows/[email protected]
    with:
      dry_run: true

  publish:
    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/')
    permissions:
      contents: read
      id-token: write
    uses: openclaw/clawhub/.github/workflows/[email protected]
    with:
      dry_run: false
    secrets:
      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

Notes:

• The reusable workflow defaults source to the caller repo.
• For monorepos, pass source_path so the workflow publishes the plugin package folder, for example source_path: extensions/codex.
• Pin the reusable workflow to a stable tag or full commit SHA. Do not run release publishing from @main.
• pull_request should use dry_run: true so CI stays non-polluting.
• Real publishes should be limited to trusted events such as workflow_dispatch or tag pushes.
• Trusted publishing without a secret only works on workflow_dispatch; tag pushes still need clawhub_token.
• Keep clawhub_token available for first publish, untrusted packages, or break-glass publishes.
• The workflow uploads the JSON result as an artifact and exposes it as workflow outputs.

sync

• Scans for local skill folders and publishes new/changed ones.
• Roots can be any folder: a skills directory or a single skill folder with SKILL.md.
• Auto-adds Clawdbot skill roots when ~/.clawdbot/clawdbot.json is present:
  • agent.workspace/skills (main agent)
  • routing.agents.*.workspace/skills (per-agent)
  • ~/.clawdbot/skills (shared)
  • skills.load.extraDirs (shared packs)
• Respects CLAWDBOT_CONFIG_PATH / CLAWDBOT_STATE_DIR and OPENCLAW_CONFIG_PATH / OPENCLAW_STATE_DIR.
• Flags:
  • --root <dir...> extra scan roots
  • --all upload without prompting
  • --dry-run show plan only
  • --bump patch|minor|major (default: patch)
  • --changelog <text> (non-interactive)
  • --tags a,b,c (default: latest)
  • --concurrency <n> (default: 4)

Telemetry:

• Sent during sync when logged in, unless CLAWHUB_DISABLE_TELEMETRY=1 (legacy CLAWDHUB_DISABLE_TELEMETRY=1).
• Details: docs/telemetry.md.