ClawHub CLI Reference: Commands, Flags, Config, and Lockfile Behavior

CLI

The CLI package is named clawhub, and its binary is clawhub.

Install it globally using npm or pnpm:

npm i -g clawhub
# or
pnpm add -g clawhub

After installation, confirm it works:

clawhub --help
clawhub login
clawhub whoami

Global flags

• --workdir <dir>: specifies the working directory (defaults to the current directory; falls back to the Clawdbot workspace if one is configured)
• --dir <dir>: defines the installation directory inside the working directory (default: skills)
• --site <url>: provides the base URL for browser-based login (default: https://clawhub.ai)
• --registry <url>: sets the API base URL (default is auto-detected, otherwise https://clawhub.ai)
• --no-input: suppresses all interactive prompts

Environment variable equivalents:

• CLAWHUB_SITE (older form: CLAWDHUB_SITE)
• CLAWHUB_REGISTRY (older form: CLAWDHUB_REGISTRY)
• CLAWHUB_WORKDIR (older form: CLAWDHUB_WORKDIR)

HTTP proxy

Standard HTTP proxy environment variables are respected by the CLI for environments behind corporate proxies or restricted networks:

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

When any of these variables is configured, the CLI directs outbound traffic through the designated proxy. HTTPS_PROXY handles HTTPS requests, while HTTP_PROXY manages plain HTTP. NO_PROXY / no_proxy is honored to exclude specific hosts or domains from proxy routing.

This setup is necessary when direct outbound connections are not permitted, such as in Docker containers, Hetzner VPS instances with proxy-only internet access, or behind corporate firewalls.

Example:

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

If no proxy variable is set, the CLI behaves as usual with direct connections.

Config file

The CLI stores your API token along with a cached registry URL.

• On macOS: ~/Library/Application Support/clawhub/config.json
• On Linux or XDG-compliant systems: $XDG_CONFIG_HOME/clawhub/config.json or ~/.config/clawhub/config.json
• On Windows: %APPDATA%\\clawhub\\config.json
• Legacy fallback: if clawhub/config.json is absent but clawdhub/config.json exists, the CLI falls back to the legacy location
• Override path: CLAWHUB_CONFIG_PATH (older form: CLAWDHUB_CONFIG_PATH)

Commands

login / auth login

• Default behavior: opens a browser to <site>/cli/auth and finishes through a loopback callback.
• Headless mode: clawhub login --token clh_...
• Remote or headless interactive mode: clawhub login --device displays a code and waits while you authenticate at <site>/cli/device.

whoami

• Confirms the stored token by calling /api/v1/whoami.

token

• Outputs the stored API token to stdout.
• Useful for feeding a local login token into CI secret configuration commands.

star <skill> / unstar <skill>

• Adds or removes a skill from your Bookmarks. The command names stay as star and unstar for backward compatibility.
• Invokes POST /api/v1/stars/<slug> and DELETE /api/v1/stars/<slug>.
• Using --yes bypasses the confirmation prompt.

search <query...>

• Makes a call to /api/v1/search?q=....
• The response contains the skill's slug, owner handle, display name, and a relevance score.
• Search ranks exact slug or name token matches above download popularity. A standalone slug token like map produces a stronger match for personal-map than the substring found inside amap.
• Popularity acts as a minor ranking signal, not a guarantee of a top result.
• If a skill is missing from search results, run clawhub inspect @owner/slug while authenticated to review owner-visible moderation diagnostics before renaming any metadata.

explore

• Shows the most recent skills using /api/v1/skills?limit=...&sort=createdAt, ordered by createdAt in descending order.
• Options:
  • --limit <n> (range 1-200, defaults to 25)
  • --sort newest|updated|rating|downloads|trending (defaults to newest). Legacy install sort aliases remain functional for backward compatibility.
  • --json (produces machine-readable output)
• Response format: <slug> v<version> <age> <summary>, with summaries truncated to 50 characters.

inspect @owner/slug

• Retrieves skill metadata and version files without performing an installation.
• --version <version>: examine a particular version (default is the latest).
• --tag <tag>: examine a version by tag (for example, latest).
• --versions: display the version history (first page).
• --limit <n>: maximum number of versions to show (1-200).
• --files: list files belonging to the chosen version.
• --file <path>: download the raw file bytes (capped at 10MB).
• --json: machine-readable output; --file includes the exact bytes as base64 and UTF-8 text when that data is present.

install @owner/slug

• Resolves the most recent version for the specified owner and skill.
• Downloads the zip archive via /api/v1/download.
• Unpacks the contents into <workdir>/<dir>/<slug>.
• Will not overwrite a pinned skill; run clawhub unpin <skill> beforehand.
• Creates:
  • <workdir>/.clawhub/lock.json (the legacy equivalent is .clawdhub)
  • <skill>/.clawhub/origin.json (the legacy equivalent is .clawdhub)

uninstall <skill>

• Deletes <workdir>/<dir>/<slug> and removes the corresponding lockfile entry.
• Sends best-effort telemetry when logged in, so active install counts can be decremented.
• In interactive mode: prompts for confirmation.
• In non-interactive mode (--no-input): requires --yes.

list

• Reads <workdir>/.clawhub/lock.json (legacy file .clawdhub).
• Displays pinned next to skills that were frozen using clawhub pin, including any optional reason provided.

pin <skill>

• Marks an installed skill as pinned within the lockfile.
• --reason <text> records the reason the skill was frozen.
• Pinned skills are ignored by update --all and refused by a direct update <skill>.
• Pinned skills also reject install --force, preventing accidental replacement of the local files.

unpin <skill>

• Removes the lockfile pin from an installed skill, allowing future updates to modify it.

update [@owner/slug] / update --all

• Generates a fingerprint from the local files.
• If the fingerprint matches a known version: no prompt is shown.
• If the fingerprint does not match:
  • by default, the operation is refused
  • with --force (or a prompt in interactive mode), the files are overwritten
• Pinned skills are never updated by --force.
• update <skill> fails immediately for pinned skills and advises you to run clawhub unpin <skill> first.
• update --all skips pinned slugs and prints a summary of which items remained frozen.

skill publish <path>

• The tool compares the local bundle fingerprint against ClawHub and exits with a success code when the content has already been published.
• By default, new skills are assigned 1.0.0; modified skills receive the next patch version.
• --version <version> lets you pick a specific version and forces publication even if the content matches an already existing version.
• --dry-run processes the publish without uploading anything; --json outputs the result in a machine-readable format.
• When the actor holds publisher access, --owner <handle> publishes under an organization or user publisher handle.
• --migrate-owner transfers an existing skill to --owner while also publishing a new version. This operation requires admin or owner permissions on both publishers.
• Ownership and review details are described in docs/publishing.md.
• Publishing a skill means it is released on ClawHub under MIT-0.
• Published skills may be freely used, modified, and redistributed without any attribution requirement.
• ClawHub does not offer paid skills or per-skill pricing.
• Legacy alias: publish <path>.

clawhub skill publish ./my-skill --dry-run
clawhub skill publish ./my-skill
clawhub skill publish ./my-skill --version 2.0.0

GitHub Actions

ClawHub's reusable skill-publish.yml workflow invokes skill publish for a single skill_path, or for each immediate skill folder located under root (the default is skills). Unchanged skills are skipped, and the same automatic patch-version logic applies.

Set dry_run: true to preview without providing a token. For actual publishing, the clawhub_token secret is required.

sync

• Scans the current working directory, the configured skills directory, and any --root <dir> folders for local skill directories that contain SKILL.md or skill.md.
• Each local skill fingerprint is compared with ClawHub; only new or changed skills are published.
• New skills are published as 1.0.0; changed skills default to the next patch version. For update batches that need a larger semver increment, use --bump minor|major.
• --dry-run displays the publish plan without uploading; --json prints a machine-readable version of that plan.
• --all publishes every new or changed skill without asking for confirmation. Without --all, interactive terminals let you choose which skills to publish.
• If the actor has publisher access, --owner <handle> publishes under an organization or user publisher handle.
• sync is strictly one-way publish only. It does not install, update, download, or report install or download telemetry.

clawhub sync --all --dry-run
clawhub sync --all
clawhub sync --root ./skills --owner openclaw --bump minor

scan --slug <slug>

• Requires clawhub login.
• Launches ClawHub ClawScan through POST /api/v1/skills/-/scan, then polls until the scan reaches a terminal state.
• Scans run asynchronously and may take a while. While queued, the terminal spinner shows the current prioritized scan position and how many scans are ahead of it.
• Published scans require ownership or publisher management access. Moderators and admins can use the same backend via clawhub-admin.
• --update is only valid with --slug; it writes successful published scan results back to the selected version.
• --output <file.zip> downloads the full report archive, which includes manifest.json, clawscan.json, skillspector.json, static-analysis.json, virustotal.json, and README.md.
• --json prints the complete poll response for use in automation.
• Local path scans are no longer supported. Upload a new version, then use scan download to retrieve the stored scan results for that submitted version.

clawhub scan --slug gifgrep
clawhub scan --slug gifgrep --version 1.2.3
clawhub scan --slug gifgrep --update --output report.zip

scan download <name>

• Requires clawhub login.
• Downloads the stored scan report ZIP for a submitted skill or plugin version, including versions that ClawHub security checks blocked or hid.
• Skill downloads use the skill slug and default to --kind skill.
• Plugin downloads use the package name and require --kind plugin.
• --version is required so authors can inspect the exact submitted version that ClawHub blocked.
• --output <file.zip> specifies the destination path.

clawhub scan download gifgrep --version 1.2.3
clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zip

GitHub Actions

ClawHub provides an official reusable workflow at /.github/workflows/skill-publish.yml for skill repositories and catalog repositories.

Typical catalog setup:

name: Skill Publish

on:
  pull_request:
  workflow_dispatch:

jobs:
  dry-run:
    if: github.event_name == 'pull_request'
    uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1
    with:
      owner: nvidia
      dry_run: true

  publish:
    if: github.event_name == 'workflow_dispatch'
    uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1
    with:
      owner: nvidia
      dry_run: false
    secrets:
      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

Notes:

• For catalog repositories, root defaults to skills.
• To process a single skill folder, provide skill_path: skills/review-helper.
• owner corresponds to the CLI --owner flag; if omitted, the skill is published under the currently authenticated user.
• When publishing V1 skills, use clawhub_token; GitHub OIDC trusted publishing is currently limited to packages.

delete <skill>

• Without --version, a skill can be soft-deleted by its owner, a moderator, or an admin.
• This action calls DELETE /api/v1/skills/{slug}.
• When an owner initiates a soft delete, the slug is held for 30 days, and the command displays the expiration time.
• Use --version <version> to remove a single non-latest version you own. This route is fail-closed and version-specific. The version number stays reserved and cannot be reused with different content. Before deleting the current latest version, publish a replacement. Platform staff do not bypass ownership in this version-only workflow.
• --reason <text> adds a moderation note to the skill and the audit log during a full soft delete.
• --note <text> serves as an alias for --reason.
• Confirmation is skipped when --yes is passed.

undelete <skill>

• A hidden skill can be restored by its owner, a moderator, or an admin.
• This action calls POST /api/v1/skills/{slug}/undelete.
• --version <version> restores only the exact artifact that was previously withdrawn by the same owner. It does not mark the restored version as latest, nor does it recreate any removed tags.
• Version restoration calls POST /api/v1/skills/{slug}/versions/{version}/restore.
• --reason <text> adds a moderation note to the skill and the audit log.
• --note <text> is an alias for --reason.
• Confirmation is skipped when --yes is passed.

hide <skill>

• A skill can be hidden by its owner, a moderator, or an admin.
• This is an alias for delete.

unhide <skill>

• A skill can be unhidden by its owner, a moderator, or an admin.
• This is an alias for undelete.

skill rename <skill> <new-name>

• Rename a skill you own while keeping the previous slug as a redirect alias.
• This action calls POST /api/v1/skills/{slug}/rename.
• Confirmation is skipped when --yes is passed.

skill merge <source> <target>

• Merge one skill you own into another skill you own.
• The source slug is removed from public listings and becomes a redirect alias pointing to the target.
• This action calls POST /api/v1/skills/{sourceSlug}/merge.
• Confirmation is skipped when --yes is passed.

transfer

• Ownership transfer workflow.
• Transfers to user handles generate a pending request that the recipient must accept.
• Transfers to organization or publisher handles take effect immediately only if the actor has admin access to both the current owner and the 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}/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

package explore [query...]

• Navigates or queries the combined package catalog with GET /api/v1/packages and GET /api/v1/packages/search.
• Intended for plugins and similar package category entries; search remains the primary search tool for skills.
• Available 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> (range 1-100, 25 by default)
  • --json

Usage 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>

• Retrieves package details without performing an installation.
• Suitable for checking plugin metadata, compatibility, verification, source, and version or file information.
• --version <version>: examine a particular version (latest is the default).
• --tag <tag>: examine a version identified by a tag (for instance, latest).
• --versions: show the version history (first page only).
• --limit <n>: limit the number of versions shown (1-100).
• --files: display files for the chosen version.
• --file <path>: retrieve a truncated UTF-8 text preview (capped at 200KB).
• --json: produce output in a machine-readable format.

package download <name>

• Determines a package version by using GET /api/v1/packages/{name}/versions/{version}/artifact.
• Pulls the artifact from the resolver's downloadUrl.
• Confirms the ClawHub SHA-256 checksum for every artifact.
• For ClawPack npm-pack artifacts, also checks npm sha512 integrity, the npm shasum, and the tarball's package.json name and version.
• Legacy ZIP artifacts are downloaded through the legacy ZIP pathway.
• Flags:
  • --version <version>: fetch a particular version.
  • --tag <tag>: fetch a version identified by a tag (default is latest).
  • -o, --output <path>: specify the output file or directory.
  • --force: replace an existing output file.
  • --json: produce machine-readable output.

Usage examples:

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

package verify <file>

• Calculates the ClawHub SHA-256, npm sha512 integrity, and npm shasum for a local artifact.
• When --package is used, resolves the expected metadata from ClawHub and compares the local file with the published artifact metadata.
• Using direct digest flags performs verification without contacting the network.
• Flags:
  • --package <name>: the package name to resolve the expected artifact metadata.
  • --version <version> or --tag <tag>: the expected package version.
  • --sha256 <hex>: the expected ClawHub SHA-256.
  • --npm-integrity <sri>: the expected npm integrity.
  • --npm-shasum <sha1>: the expected npm shasum.
  • --json: produce machine-readable output.

Usage 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 validate <source>

• Executes the Plugin Inspector bundled with the ClawHub CLI against a local plugin package directory.
• By default, validation is offline and static, without locating or importing a local OpenClaw installation.
• Hard compatibility failures cause a non-zero exit code. Warnings are displayed but the process exits zero.
• Options:
  • --out <dir>: directory for Plugin Inspector report output.
  • --openclaw <path>: validate against a specific local OpenClaw checkout.
  • --runtime: enable runtime capture, which imports plugin code.
  • --allow-execute: allow runtime capture within an isolated workspace.
  • --no-mock-sdk: disable the mocked OpenClaw SDK during runtime capture.
  • --json: output in machine-readable format.

Example:

clawhub package validate ./example-plugin

If the validation reports an issue with a package, manifest, SDK import, or artifact, consult Plugin validation fixes and then rerun the command.

package delete <name>

• Without --version, performs a soft delete of a package and all its releases.
• --version <version> removes one owned, non-latest release via a fail-closed, version-specific operation. The version number stays reserved and cannot be republished with different content. Publish a replacement before deleting the current latest version. This version-only action requires the package owner or an org publisher admin; platform staff cannot bypass package ownership.
• Whole-package soft deletion requires the package owner, an org publisher owner or admin, a platform moderator, or a platform admin.
• Options:
  • --version <version>: withdraw a single non-latest version.
  • --yes: skip confirmation prompts.
  • --json: output in machine-readable format.

Example:

clawhub package delete @openclaw/example-plugin --yes
clawhub package delete @openclaw/example-plugin --version 1.2.3 --yes

package undelete <name>

• Recovers a soft-deleted package and its releases.
• Requires the package owner, an org publisher owner or admin, a platform moderator, or a platform admin.
• Invokes POST /api/v1/packages/{name}/undelete.
• --version <version> restores only the specific retained release previously withdrawn by the same owner actor. It does not mark the release as latest or recreate removed package tags or dist-tags.
• Version restoration calls POST /api/v1/packages/{name}/versions/{version}/restore.
• Options:
  • --version <version>: restore one owner-withdrawn release.
  • --yes: skip confirmation prompts.
  • --json: output in machine-readable format.

Example:

clawhub package undelete @openclaw/example-plugin --yes

package transfer <name>

• Moves a package to a different publisher.
• Requires admin access to both the current package owner and the destination publisher, unless a platform admin performs the transfer.
• Scoped package names must be transferred to the corresponding scope owner.
• Calls POST /api/v1/packages/{name}/transfer.
• Options:
  • --to <owner>: handle of the destination publisher.
  • --reason <text>: optional audit reason.
  • --json: output in machine-readable format.

Example:

clawhub package transfer @openclaw/example-plugin --to openclaw

package report

• Authenticated command to report a package to moderators.
• Calls POST /api/v1/packages/{name}/report.
• Reports are at the package level, optionally linked to a version, and become visible to moderators for review.
• Reports do not automatically hide packages or block downloads on their own.
• Options:
  • --version <version>: optional package version to include in the report.
  • --reason <text>: required reason for the report.
  • --json: output in machine-readable format.

Example:

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

package moderation-status

• Owner command to inspect a package's moderation visibility.
• Calls GET /api/v1/packages/{name}/moderation.
• Displays the current package scan state, number of open reports, latest release manual moderation status, download block state, and moderation reasons.
• Options:
  • --json: output in machine-readable format.

Example:

clawhub package moderation-status @openclaw/example-plugin

package readiness <name>

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

Example:

clawhub package readiness @openclaw/example-plugin

package migration-status <name>

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

Example:

clawhub package migration-status @openclaw/example-plugin

publisher create <handle>

• Creates an org publisher owned by the authenticated user.
• The handle is normalized to lowercase and can be provided with or without @.
• Newly created org publishers are not trusted or official by default.
• Fails if the handle is already taken by an existing publisher, user, or reserved route.

clawhub publisher create opik --display-name "Opik"

package publish <source>

• A code plugin or bundle plugin can be published through POST /api/v1/packages.

• <source> supports the following inputs:

  • A local folder path: ./my-plugin
  • A local ClawPack npm-pack tarball: ./my-plugin-1.2.3.tgz
  • A GitHub repository: owner/repo or owner/repo@ref
  • A GitHub URL: https://github.com/owner/repo

• Metadata is automatically identified from package.json, openclaw.plugin.json, and actual OpenClaw bundle indicators like .codex-plugin/plugin.json, .claude-plugin/plugin.json, and .cursor-plugin/plugin.json.

• Sources provided via .tgz are handled as ClawPack. The CLI transmits the exact npm-pack bytes and only uses the extracted package/ content for validation and prefilling metadata.

• Before upload, code-plugin directories are compressed into a ClawPack npm tarball so OpenClaw installations can verify the precise artifact. Bundle-plugin directories continue to follow the extracted-file publish path.

• For sources from GitHub, source attribution is automatically filled from the repository, resolved commit, ref, and subpath.

• For local directories, source attribution is automatically detected from a local git repository when the origin remote points to GitHub.

• External code plugins must explicitly declare openclaw.compat.pluginApi and openclaw.build.openclawVersion. The top-level package.json.version is never used as a fallback during publish validation.

• Running --dry-run shows the resolved publish payload without performing an upload.

• --json produces output in a machine-readable format suitable for CI.

• When the actor has publisher permissions, --owner <handle> publishes under either a user or organization publisher handle.

• Scoped package names must align with the chosen owner. Refer to docs/publishing.md.

• Existing flags (--family, --name, --version, --source-repo, --source-commit, --source-ref, --source-path) continue to function as overrides.

• A GITHUB_TOKEN is required for private GitHub repositories.

clawhub package publish ./plugin.tgz --owner openclaw

Recommended local flow

Start by using --dry-run so you can verify the resolved package metadata and source attribution before generating 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, publishing from a folder builds and uploads a ClawPack artifact originating from the package directory:

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 require a minimal set of OpenClaw metadata inside package.json. This compact manifest is sufficient 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"
    }
  }
}

Mandatory fields:

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

Remarks:

• package.json.version represents your package release version, but it is not employed as a fallback for OpenClaw compatibility or build validation.
• openclaw.hostTargets and openclaw.environment are optional metadata entries. ClawHub may display them if present, but they are not mandatory for publishing.
• openclaw.compat.minGatewayVersion and openclaw.build.pluginSdkVersion are optional extras if you want to publish more detailed compatibility metadata.
• If you are running an older clawhub CLI version, upgrade before publishing so the local preflight checks execute prior to upload.
• When validation returns a remediation code, consult Plugin validation fixes.

GitHub Actions

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

Typical caller configuration:

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/package-publish.yml@v0.12.0
    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/package-publish.yml@v0.12.0
    with:
      dry_run: false
    secrets:
      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

Remarks:

• By default, the reusable workflow source points to the caller's repository.
• In a monorepo setup, supply source_path so the workflow publishes the plugin package folder, for instance source_path: extensions/codex.
• Pin the reusable workflow to a fixed tag or a complete commit SHA. Avoid running release publishing from @main.
• Use pull_request with dry_run: true to keep CI free of side effects.
• Restrict actual publishes to trusted events like workflow_dispatch or tag pushes.
• Trusted publishing without a secret functions only on workflow_dispatch; tag pushes still require clawhub_token.
• Keep clawhub_token accessible for the initial publish, untrusted packages, or emergency break-glass scenarios.
• The workflow uploads the JSON result as an artifact and makes it available as workflow outputs.

package trusted-publisher get <name>

• Displays the GitHub Actions trusted publisher configuration for a package.
• Run this after setting up config to verify the repository, workflow filename, and optional environment pin.
• Options:
  • --json: output in machine-readable format.

Example:

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

package trusted-publisher set <name>

• Adds or updates GitHub Actions trusted publisher configuration for an existing package.
• The package must already exist via normal manual or token-based clawhub package publish.
• Once configured, future supported GitHub Actions publishes can rely on OIDC/trusted publishing without needing a long-lived ClawHub token.
• --repository <repo> is required to be owner/repo.
• --workflow-filename <file> must correspond to the workflow file name in .github/workflows/.
• --environment <name> is optional. If set, the GitHub Actions environment in the OIDC claim must match exactly.
• When this command runs, ClawHub verifies the configured GitHub repository. Public repositories can be verified through public GitHub metadata. Private repositories require ClawHub to have GitHub access to that repository, for example via a future ClawHub GitHub App installation or another authorized GitHub integration.
• Options:
  • --repository <repo>: GitHub repository, for example openclaw/example-plugin.
  • --workflow-filename <file>: workflow file name, for example package-publish.yml.
  • --environment <name>: optional exact-match GitHub Actions environment.
  • --json: output in machine-readable format.

Example:

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

package trusted-publisher delete <name>

• Deletes trusted publisher configuration from a package.
• Use this as a rollback when the workflow, repository, or environment pin needs to be disabled or recreated.
• Future real publishes must use normal authenticated publishing until config is set again.
• Options:
  • --json: output in machine-readable format.

Example:

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

Install telemetry

• Sent after clawhub install <slug> when logged in, unless CLAWHUB_DISABLE_TELEMETRY=1 is set.
• Reporting is best-effort. Install commands do not fail if telemetry is unavailable.
• Details: docs/telemetry.md.