Using ClawHub
CLI
CLI
CLI package: clawhub, bin: clawhub.
Install it globally with npm or pnpm:
npm i -g clawhub# orpnpm add -g clawhubThen verify it:
clawhub --helpclawhub loginclawhub whoamiGlobal 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, elsehttps://clawhub.ai)--no-input: disable prompts
Env equivalents:
CLAWHUB_SITE(legacyCLAWDHUB_SITE)CLAWHUB_REGISTRY(legacyCLAWDHUB_REGISTRY)CLAWHUB_WORKDIR(legacyCLAWDHUB_WORKDIR)
HTTP proxy
The CLI respects standard HTTP proxy environment variables for systems behind corporate proxies or restricted networks:
HTTPS_PROXY/https_proxyHTTP_PROXY/http_proxyNO_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:3128export NO_PROXY=localhost,127.0.0.1clawhub 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.jsonor~/.config/clawhub/config.json - Windows:
%APPDATA%\\clawhub\\config.json - Legacy fallback: if
clawhub/config.jsondoes not exist yet butclawdhub/config.jsondoes, the CLI reuses the legacy path - override:
CLAWHUB_CONFIG_PATH(legacyCLAWDHUB_CONFIG_PATH)
Commands
login / auth login
- Default: opens browser to
<site>/cli/authand completes via loopback callback. - Headless:
clawhub login --token clh_... - Remote/headless interactive:
clawhub login --deviceprints a code and waits while you authorize it at<site>/cli/device.
whoami
- Verifies the stored token via
/api/v1/whoami.
token
- Prints the stored API token to stdout.
- Useful for piping a local login token into CI secret setup commands.
star <skill> / unstar <skill>
- Adds/removes a skill from your highlights.
- Calls
POST /api/v1/stars/<slug>andDELETE /api/v1/stars/<slug>. --yesskips confirmation.
search <query...>
- Calls
/api/v1/search?q=.... - Output includes the skill slug, owner handle, display name, and relevance score.
- Search favors exact slug/name token matches before download popularity. A standalone slug token such as
mapmatchespersonal-mapmore strongly than the substring insideamap. - Popularity is a small ranking prior, not a guarantee of top placement.
- If a skill should appear but does not, run
clawhub inspect @owner/slugwhile logged in to check owner-visible moderation diagnostics before renaming metadata.
explore
- Lists newest skills via
/api/v1/skills?limit=...&sort=createdAt(sorted bycreatedAtdesc). - Flags:
--limit <n>(1-200, default: 25)--sort newest|updated|rating|installs|installsAllTime|trending(default: newest)--json(machine-readable output)
- Output:
<slug> v<version> <age> <summary>(summary truncated to 50 chars).
inspect @owner/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 @owner/slug
- Resolves latest version for the named owner and skill.
- Downloads zip via
/api/v1/download. - Extracts into
<workdir>/<dir>/<slug>. - Refuses to overwrite pinned skills; run
clawhub unpin <skill>first. - Writes:
<workdir>/.clawhub/lock.json(legacy.clawdhub)<skill>/.clawhub/origin.json(legacy.clawdhub)
uninstall <skill>
- Removes
<workdir>/<dir>/<slug>and deletes the lockfile entry. - Sends best-effort telemetry while logged in so current install counts can be deactivated.
- Interactive: asks for confirmation.
- Non-interactive (
--no-input): requires--yes.
list
- Reads
<workdir>/.clawhub/lock.json(legacy.clawdhub). - Shows
pinnednext to skills frozen withclawhub pin, including the optional reason.
pin <skill>
- Marks an installed skill as pinned in the lockfile.
--reason <text>records why the skill is frozen.- Pinned skills are skipped by
update --alland rejected by directupdate <skill>. - Pinned skills also reject
install --forceso the local bytes cannot be replaced accidentally.
unpin <skill>
- Removes the lockfile pin from an installed skill so future updates can modify it.
update [@owner/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)
- Pinned skills are never updated by
--force. update <skill>fails fast for pinned skills and tells you to runclawhub unpin <skill>first.update --allskips pinned slugs and prints a summary of what stayed frozen.
skill publish <path>
- Compares the local bundle fingerprint with ClawHub and exits successfully when the content is already published.
- New skills default to
1.0.0; changed skills default to the next patch version. --version <version>explicitly selects a version and publishes even when the content matches an existing version.--dry-runresolves the publish without uploading;--jsonprints a machine-readable result.--owner <handle>publishes under an org/user publisher handle when the actor has publisher access.--migrate-ownermoves an existing skill to--ownerwhile publishing a new version. Requires admin/owner access on both publishers.- Owner and review behavior is explained in
docs/publishing.md. - Publishing a skill means it is released under
MIT-0on 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>.
clawhub skill publish ./my-skill --dry-runclawhub skill publish ./my-skillclawhub skill publish ./my-skill --version 2.0.0GitHub Actions
ClawHub's reusable
skill-publish.yml
workflow calls skill publish for one skill_path, or for each immediate skill
folder under root (default: skills). It skips unchanged skills and uses the
same automatic patch-version behavior.
Set dry_run: true to preview without a token. Real publishes require the
clawhub_token secret.
scan --slug <slug>
- Requires
clawhub login. - Runs ClawHub ClawScan through
POST /api/v1/skills/-/scan, then polls until the scan is terminal. - Scans are asynchronous and may take time to complete. While queued, the terminal spinner shows the current prioritized scan position and how many scans are ahead.
- Published scans require ownership or publisher management access. Moderators/admins can use the same backend through
clawhub-admin. --updateis valid only with--slug; it writes successful published scan results back to the selected version.--output <file.zip>downloads the full report archive withmanifest.json,clawscan.json,skillspector.json,static-analysis.json,virustotal.json, andREADME.md.--jsonprints the full poll response for automation.- Local path scans are no longer supported. Upload a new version, then use
scan downloadto retrieve the stored scan results for that submitted version.
clawhub scan --slug gifgrepclawhub scan --slug gifgrep --version 1.2.3clawhub scan --slug gifgrep --update --output report.zipscan download <name>
- Requires
clawhub login. - Downloads the stored scan report ZIP for a submitted skill or plugin version, including versions that were blocked or hidden by ClawHub security checks.
- Skill downloads use the skill slug and default to
--kind skill. - Plugin downloads use the package name and require
--kind plugin. --versionis required so authors inspect the exact submitted version that ClawHub blocked.--output <file.zip>chooses the destination path.
clawhub scan download gifgrep --version 1.2.3clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zipGitHub Actions
ClawHub ships an official reusable workflow at
/.github/workflows/skill-publish.yml
for skill repos and catalog repos.
Typical catalog setup:
name: Skill Publish on: pull_request: workflow_dispatch: jobs: dry-run: if: github.event_name == 'pull_request' uses: OmeniaClaw/clawhub/.github/workflows/skill-publish.yml@v1 with: owner: nvidia dry_run: true publish: if: github.event_name == 'workflow_dispatch' uses: OmeniaClaw/clawhub/.github/workflows/skill-publish.yml@v1 with: owner: nvidia dry_run: false secrets: clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}Notes:
rootdefaults toskillsfor catalog repos.- Pass
skill_path: skills/review-helperto process one skill folder. ownermaps to the CLI--ownerflag; omit it to publish as the authenticated user.- V1 skill publishing uses
clawhub_token; GitHub OIDC trusted publishing is package-only for now.
delete <skill>
- Without
--version, soft-delete a skill (owner, moderator, or admin). - Calls
DELETE /api/v1/skills/{slug}. - Owner-initiated soft deletes reserve the slug for 30 days; the command prints the expiry time.
--version <version>permanently deletes one owned non-latest version through a fail-closed, version-specific route. Deleted versions cannot be restored or republished. Publish a replacement before deleting the current latest version. Platform staff do not bypass ownership for this version-only flow.--reason <text>records a moderation note on a whole-skill soft-delete and audit log.--note <text>is an alias for--reason.--yesskips confirmation.
undelete <skill>
- Restore a hidden skill (owner, moderator, or admin).
- There is no version undelete; permanently deleted versions cannot be restored.
- 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.--yesskips confirmation.
hide <skill>
- Hide a skill (owner, moderator, or admin).
- Alias for
delete.
unhide <skill>
- Unhide a skill (owner, moderator, or admin).
- Alias for
undelete.
skill rename <skill> <new-name>
- Rename an owned skill and keep the previous slug as a redirect alias.
- Calls
POST /api/v1/skills/{slug}/rename. --yesskips confirmation.
skill merge <source> <target>
- 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. --yesskips confirmation.
transfer
- Ownership transfer workflow.
- Transfers to user handles create a pending request that the recipient accepts.
- Transfers to org/publisher handles apply immediately only when the actor has admin access to both the current owner and destination publisher.
- Subcommands:
transfer request <skill> <handle> [--message "..."] [--yes]transfer list [--outgoing]transfer accept <skill> [--yes]transfer reject <skill> [--yes]transfer cancel <skill> [--yes]
- Endpoints:
POST /api/v1/skills/{slug}/transferPOST /api/v1/skills/{slug}/transfer/acceptPOST /api/v1/skills/{slug}/transfer/rejectPOST /api/v1/skills/{slug}/transfer/cancelGET /api/v1/transfers/incomingGET /api/v1/transfers/outgoing
package explore [query...]
- Browses or searches the unified package catalog via
GET /api/v1/packagesandGET /api/v1/packages/search. - Use this for plugins and other package-family entries; top-level
searchremains 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-pluginclawhub package explore --family code-plugin --os darwin --requires-desktopclawhub package explore --family code-plugin --artifact-kind npm-packclawhub package explore --npm-mirrorclawhub package explore episodic-claw --family code-pluginpackage 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
sha512integrity, npm shasum, and the tarball'spackage.jsonname/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 @OmeniaClaw/example-plugin --tag latestclawhub package download @OmeniaClaw/example-plugin --version 1.2.3 -o artifacts/package verify <file>
- Computes ClawHub SHA-256, npm
sha512integrity, 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 @OmeniaClaw/example-plugin --version 1.2.3clawhub package verify ./example-plugin-1.2.3.tgz --sha256 <hex>package validate <source>
- Runs the ClawHub CLI's bundled Plugin Inspector against a local plugin package folder.
- Defaults to offline/static validation, without locating or importing a local OmeniaClaw checkout.
- Hard compatibility errors exit non-zero. Warning-only findings are printed but exit zero.
- Flags:
--out <dir>: write Plugin Inspector reports to this directory.--OmeniaClaw <path>: inspect against an explicit local OmeniaClaw checkout.--runtime: enable runtime capture; imports plugin code.--allow-execute: allow runtime capture in an isolated workspace.--no-mock-sdk: disable mocked OmeniaClaw SDK during runtime capture.--json: machine-readable output.
Example:
clawhub package validate ./example-pluginIf validation reports a package, manifest, SDK import, or artifact finding, see Plugin validation fixes, then rerun the command.
package delete <name>
- Without
--version, soft-deletes a package and all releases. --version <version>permanently deletes one owned non-latest release through a fail-closed, version-specific route. Deleted versions cannot be restored or republished. Publish a replacement before deleting the current latest version. This version-only flow requires the package owner or an org publisher admin; platform staff do not bypass package ownership.- Whole-package soft-delete requires the package owner, an org publisher owner/admin, platform moderator, or platform admin.
- Flags:
--version <version>: permanently delete one non-latest version.--yes: skip confirmation.--json: machine-readable output.
Example:
clawhub package delete @OmeniaClaw/example-plugin --yesclawhub package delete @OmeniaClaw/example-plugin --version 1.2.3 --yespackage undelete <name>
- Restores a soft-deleted package and releases.
- There is no version undelete; permanently deleted versions cannot be restored.
- Requires the package owner, an org publisher owner/admin, platform moderator, or platform admin.
- Calls
POST /api/v1/packages/{name}/undelete. - Flags:
--yes: skip confirmation.--json: machine-readable output.
Example:
clawhub package undelete @OmeniaClaw/example-plugin --yespackage transfer <name>
- Transfers a package to another publisher.
- Requires admin access to both the current package owner and destination publisher, unless performed by a platform admin.
- Scoped package names must transfer to the matching scope owner.
- Calls
POST /api/v1/packages/{name}/transfer. - Flags:
--to <owner>: destination publisher handle.--reason <text>: optional audit reason.--json: machine-readable output.
Example:
clawhub package transfer @OmeniaClaw/example-plugin --to OmeniaClawpackage 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 become visible to moderators for review.
- 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 @OmeniaClaw/example-plugin --version 1.2.3 --reason "suspicious native payload"package moderation-status
- Owner 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 @OmeniaClaw/example-pluginpackage readiness <name>
- Checks whether a package is ready for future OmeniaClaw consumption.
- Calls
GET /api/v1/packages/{name}/readiness. - Reports blockers for official status, ClawPack availability, artifact digest, source provenance, OmeniaClaw compatibility, host targets, environment metadata, and scan state.
- Flags:
--json: machine-readable output.
Example:
clawhub package readiness @OmeniaClaw/example-pluginpackage migration-status <name>
- Shows operator-oriented migration status for a package that may replace a bundled OmeniaClaw 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 @OmeniaClaw/example-pluginpublisher create <handle>
- Creates an org publisher owned by the authenticated user.
- The handle is normalized to lowercase and may be passed with or without
@. - Newly created org publishers are not trusted/official by default.
- Fails if the handle is already used by an existing publisher, user, or reserved route.
clawhub publisher create opik --display-name "Opik"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/repoorowner/repo@ref - GitHub URL:
https://github.com/owner/repo
- Local folder path:
- Metadata is auto-detected from
package.json,OmeniaClaw.plugin.json, and real OmeniaClaw bundle markers such as.codex-plugin/plugin.json,.claude-plugin/plugin.json, and.cursor-plugin/plugin.json. .tgzsources are treated as ClawPack. The CLI uploads the exact npm-pack bytes and uses the extractedpackage/contents only for validation and metadata prefill.- Code-plugin folders are packed into a ClawPack npm tarball before upload so OmeniaClaw 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
OmeniaClaw.compat.pluginApiandOmeniaClaw.build.OmeniaClawVersionexplicitly. Top-levelpackage.json.versionis not used as a fallback for publish validation. --dry-runpreviews the resolved publish payload without uploading.--jsonemits machine-readable output for CI.--owner <handle>publishes under a user or org publisher handle when the actor has publisher access.- Scoped package names must match the selected owner. See
docs/publishing.md. - Existing flags (
--family,--name,--version,--source-repo,--source-commit,--source-ref,--source-path) still work as overrides. - Private GitHub repos require
GITHUB_TOKEN.
clawhub package publish ./plugin.tgz --owner OmeniaClawRecommended local flow
Use --dry-run first so you can confirm the resolved package metadata and
source attribution before creating a live release:
npm packclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-runclawhub package publish ./my-plugin-1.2.3.tgz --family code-pluginLocal 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-runclawhub package publish ./my-plugin --family code-pluginMinimal package.json for --family code-plugin
External code plugins need a small amount of OmeniaClaw metadata in
package.json. This minimal manifest is enough for a successful publish:
{ "name": "@myorg/OmeniaClaw-my-plugin", "version": "1.0.0", "type": "module", "OmeniaClaw": { "extensions": ["./index.ts"], "compat": { "pluginApi": ">=2026.3.24-beta.2" }, "build": { "OmeniaClawVersion": "2026.3.24-beta.2" } }}Required fields:
OmeniaClaw.compat.pluginApiOmeniaClaw.build.OmeniaClawVersion
Notes:
package.json.versionis your package release version, but it is not used as a fallback for OmeniaClaw compatibility/build validation.OmeniaClaw.hostTargetsandOmeniaClaw.environmentare optional metadata. ClawHub may surface them when present, but they are not required for publish.OmeniaClaw.compat.minGatewayVersionandOmeniaClaw.build.pluginSdkVersionare optional extras if you want to publish more detailed compatibility metadata.- If you are using an older
clawhubCLI release, upgrade before publishing so the local preflight checks run before upload. - If validation reports a remediation code, see Plugin validation fixes.
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: OmeniaClaw/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: OmeniaClaw/clawhub/.github/workflows/[email protected] with: dry_run: false secrets: clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}Notes:
- The reusable workflow defaults
sourceto the caller repo. - For monorepos, pass
source_pathso the workflow publishes the plugin package folder, for examplesource_path: extensions/codex. - Pin the reusable workflow to a stable tag or full commit SHA. Do not run release publishing from
@main. pull_requestshould usedry_run: trueso CI stays non-polluting.- Real publishes should be limited to trusted events such as
workflow_dispatchor tag pushes. - Trusted publishing without a secret only works on
workflow_dispatch; tag pushes still needclawhub_token. - Keep
clawhub_tokenavailable for first publish, untrusted packages, or break-glass publishes. - The workflow uploads the JSON result as an artifact and exposes it as workflow outputs.
package trusted-publisher get <name>
- Shows the GitHub Actions trusted publisher config for a package.
- Use this after setting config to confirm the repository, workflow filename, and optional environment pin.
- Flags:
--json: machine-readable output.
Example:
clawhub package trusted-publisher get @OmeniaClaw/example-pluginpackage trusted-publisher set <name>
- Attaches or replaces GitHub Actions trusted publisher config for an existing package.
- The package must be created first through normal manual or token-authenticated
clawhub package publish. - After config is set, future supported GitHub Actions publishes can use OIDC/trusted publishing without a long-lived ClawHub token.
--repository <repo>must beowner/repo.--workflow-filename <file>must match the workflow file name in.github/workflows/.--environment <name>is optional. When configured, the GitHub Actions environment in the OIDC claim must match exactly.- ClawHub verifies the configured GitHub repository when this command runs. Public repositories can be verified through public GitHub metadata. Private repositories require ClawHub to have GitHub access to that repository, for example through a future ClawHub GitHub App installation or another authorized GitHub integration.
- Flags:
--repository <repo>: GitHub repository, for exampleOmeniaClaw/example-plugin.--workflow-filename <file>: workflow file name, for examplepackage-publish.yml.--environment <name>: optional exact-match GitHub Actions environment.--json: machine-readable output.
Example:
clawhub package trusted-publisher set @OmeniaClaw/example-plugin \ --repository OmeniaClaw/example-plugin \ --workflow-filename package-publish.yml \ --environment releasepackage trusted-publisher delete <name>
- Removes trusted publisher config from a package.
- Use this as rollback if the workflow, repository, or environment pin needs to be disabled or re-created.
- Future real publishes must use normal authenticated publishing until config is set again.
- Flags:
--json: machine-readable output.
Example:
clawhub package trusted-publisher delete @OmeniaClaw/example-pluginInstall telemetry
- Sent after
clawhub install <slug>when logged in, unlessCLAWHUB_DISABLE_TELEMETRY=1is set. - Reporting is best-effort. Install commands do not fail if telemetry is unavailable.
- Details:
docs/telemetry.md.