clawhub

clawhub

ClawHub CLI — install, update, search, and publish agent skills plus OpenClaw packages.

Install

# From this repo (shortcut script at repo root)
bun clawhub --help

# Once published to npm
# npm i -g clawhub

Auth (publish)

clawhub login
# or
clawhub auth login

# Remote/headless browser approval
clawhub login --device

# or (token paste / headless)
clawhub login --token clh_...

# print the stored token for CI setup
clawhub token

Notes:

• Browser login opens https://clawhub.ai/cli/auth and completes via a loopback callback.
• Device login prints a one-time code and waits while you approve it at https://clawhub.ai/cli/device.
• Default config path:
  • 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 via CLAWHUB_CONFIG_PATH (legacy CLAWDHUB_CONFIG_PATH).

Examples

clawhub search "postgres backups"
clawhub install @openclaw/demo
clawhub pin bear-notes --reason "scanner-flagged while awaiting moderation"
clawhub update --all
clawhub update --all --no-input --force
clawhub unpin bear-notes
clawhub skill publish ./my-skill-pack --slug my-skill-pack --name "My Skill Pack" --changelog "Fixes + docs"
clawhub skill publish ./org-skill --owner openclaw --changelog "Org publish"
clawhub sync --all --dry-run
clawhub sync --all
clawhub package explore --family skill
clawhub package explore --family code-plugin
clawhub package inspect @openclaw/example-plugin
clawhub package download @openclaw/example-plugin --tag latest
clawhub package verify ./example-plugin-1.0.0.tgz --package @openclaw/example-plugin --version 1.0.0
clawhub package validate ./example-plugin
clawhub package publish openclaw/example-plugin
clawhub package publish openclaw/example-plugin@v1.0.0
clawhub package publish https://github.com/openclaw/example-plugin --dry-run
clawhub package publish ./example-plugin-1.0.0.tgz --dry-run
clawhub package publish ./example-plugin

Publish code plugins

For ClawPack publish, create the npm-pack tarball yourself and upload that exact .tgz:

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

For local plugin folders, start with a dry run:

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

For code plugins, folder publish builds and uploads a ClawPack artifact from the package folder. Bundle-plugin folders still use the extracted-file publish path.

Use clawhub package download to resolve the published artifact through ClawHub's explicit artifact route. ClawPack downloads are verified against npm integrity/shasum plus ClawHub SHA-256; legacy package versions still download as ZIPs.

code-plugin packages must declare these package.json fields:

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

Minimal example:

{
  "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"
    }
  }
}

package.json.version does not replace these OpenClaw-specific fields. Add openclaw.compat.minGatewayVersion and openclaw.build.pluginSdkVersion when you want richer compatibility metadata, but they are not required for publish.

GitHub Actions

This repo also provides an official reusable workflow for plugin repos:

• .github/workflows/package-publish.yml

Use dry_run: true on pull requests and reserve real publishes for trusted events such as workflow_dispatch or tag pushes with a CLAWHUB_TOKEN secret. For monorepos, pass source_path to publish the plugin package folder, for example source_path: extensions/codex.

Package trusted publishing starts after the first normal authenticated publish creates the package row. Then a package manager can attach GitHub Actions OIDC config for future supported publishes:

clawhub package trusted-publisher set @openclaw/example-plugin \
  --repository openclaw/example-plugin \
  --workflow-filename package-publish.yml \
  --environment release

clawhub package trusted-publisher get @openclaw/example-plugin
clawhub package trusted-publisher delete @openclaw/example-plugin

--environment is optional and exact-match sensitive. If configured, the GitHub Actions environment in the OIDC claim must match. Tag-push real publishes still need clawhub_token unless the reusable workflow adds tag OIDC support.

Maintainers

The clawhub npm package is released separately from the ClawHub app deploy.

• Release workflow: .github/workflows/clawhub-cli-npm-release.yml
• Release model: manual-only, stable tags only (vX.Y.Z), with a preflight run before the real publish
• Publish auth: npm trusted publishing through the npm-release GitHub environment

Development

The supported verification flow for this package is package-local:

bun run --cwd packages/clawhub test
bun run --cwd packages/clawhub verify:build
bun run --cwd packages/clawhub test:artifact
bun run --cwd packages/clawhub verify

test runs source tests only. test:artifact builds dist/ and runs a small smoke suite against the built CLI entrypoint.

Defaults

• Site: https://clawhub.ai (override via --site or CLAWHUB_SITE, legacy CLAWDHUB_SITE)
• Registry: discovered from /.well-known/clawhub.json on the site (legacy /.well-known/clawdhub.json; override via --registry or CLAWHUB_REGISTRY)
• Workdir: current directory (falls back to Clawdbot workspace if configured; override via --workdir or CLAWHUB_WORKDIR)
• Install dir: ./skills under workdir (override via --dir)