Gibwork CLI

TypeScript command-line interface for @gibwork/sdk.

The CLI signs wallet-authenticated requests and Solana transactions locally. It does not send private keys to Gibwork, persist private-key contents, or accept a raw private key as a command-line argument.

Requirements

• Node.js 22 or newer
• For wallet-authenticated operations, a Solana private key supported by the SDK: a base58-encoded 32-byte seed or 64-byte secret key, or a JSON array containing 32 or 64 bytes

Installation

Install the CLI globally with npm:

npm install --global @gibwork/cli
gibwork --help

The SDK and all other runtime dependencies are installed automatically. To run the CLI without a global installation:

npx @gibwork/cli --help

Agent skills

Version 0.2.4 bundles Gibwork skill 0.1.5 for Codex and Claude Code, with SDK 0.2.0 and MCP 0.3.1. It includes task lookup by ID, discovery, paid submissions, and recovery instructions. Install a copy from the bundled payload:

gibwork skills install codex
gibwork skills install claude
gibwork skills install codex --scope project
gibwork --json skills status
gibwork skills update codex --dry-run
gibwork skills update codex
gibwork skills remove claude

The default scope is user; --scope project always uses the current directory. Use the same client and scope for status, update, and removal. Status accepts an optional client and otherwise reports both. These commands work offline after the CLI is installed and require no wallet, agent executable, or agent login. Invoke $gibwork in Codex or /gibwork in Claude Code; restart the client if the skill is not visible yet. Installing instructions does not configure MCP or grant permission to perform Gibwork operations.

| Client | User scope | Project scope | | ----------- | -------------------------- | ------------------------------ | | Codex | ~/.agents/skills/gibwork | <cwd>/.agents/skills/gibwork | | Claude Code | ~/.claude/skills/gibwork | <cwd>/.claude/skills/gibwork |

For Claude user installs, CLAUDE_CONFIG_DIR overrides ~/.claude (relative values resolve from cwd). Codex uses the canonical .agents location regardless of CODEX_HOME; status reports legacy ~/.codex/skills/gibwork and alternate scope copies as potential duplicates. It does not move or delete those copies.

Repeated installation is a no-op. Updates copy the running CLI's bundled version; to obtain newer instructions, update the CLI first, then run skills update. CLI upgrades do not silently update installed skills. Installed files are copies and survive package removal or expiration of an npx cache.

Install, update, and remove accept --dry-run to show actions and conflicts without writing anything. Edited, missing, or added files and newer installed versions are preserved by default. --force explicitly permits supported replacement and preserves a backup under ~/.gibwork/skill-backups or <cwd>/.gibwork/skill-backups; output includes its path. --yes does not imply --force. An unmanaged copy can be adopted with install --force; update and remove always refuse unmanaged directories. Modified managed removal also needs --force and creates a backup. Symlinked destinations or payload entries are refused.

Ownership and hashes live in .gibwork-install.json inside the installed skill. Status reports absent, current, update-available, newer-installed, modified, or unmanaged. JSON follows the existing {ok, data} / {ok, error} envelope. Operational failures use SKILLS_ERROR (exit 1), with a details.reason such as MODIFIED, UNMANAGED, UNSAFE_PATH, or INSTALL_IN_PROGRESS. Invalid options and credential-input flags use USAGE_ERROR (exit 2). Dry-run conflicts are successful inspection results with action: "conflict".

Operations use an exclusive gibwork.gibwork-lock beside the destination and staged directory replacement. If interrupted, inspect the reported lock JSON and its destination, previous, and stage paths. Verify that no installer is running, preserve recoverable files, restore the previous directory if necessary, and only then remove the lock. Status never clears a lock or performs recovery automatically. Temporary recovery directories are retained when rollback fails; move recovered personal content outside agent discovery directories.

Wallet configuration

The preferred local setup is an owner-only Solana keypair file:

chmod 600 ~/.config/gibwork/id.json
gibwork --profile stage config set keypair-path ~/.config/gibwork/id.json
gibwork --profile stage wallet doctor

Configuration stores only the resolved keypair path. On macOS it is written to ~/Library/Application Support/gibwork/config.json; on Linux it follows $XDG_CONFIG_HOME and defaults to ~/.config/gibwork/config.json; on Windows it uses %APPDATA%\gibwork\config.json.

Credential sources are resolved in this order:

1. --keypair <path> or --private-key-stdin
2. GIBWORK_KEYPAIR_PATH or GIBWORK_PRIVATE_KEY
3. The selected profile's keypair-path

Only one credential source at each priority may be present. Raw keys are never accepted using --private-key, because arguments may be recorded in shell history or exposed in process listings.

For a secret manager, pipe the value without storing it in CLI configuration:

secret-manager read solana-key | gibwork --private-key-stdin wallet address

For CI, inject GIBWORK_PRIVATE_KEY through the CI system's secret facility:

# GIBWORK_PRIVATE_KEY is supplied by the CI secret store.
gibwork --json task list

Do not commit keys or place them in shell scripts. The CLI does not load .env files implicitly.

Environments and profiles

Stage is the default. Set reusable profile values with:

gibwork --profile production config set environment production
gibwork --profile production config set keypair-path /secure/path/id.json
gibwork config set default-profile production
gibwork config list

Global flags and environment variables override profile settings:

CLI flag > environment variable > selected profile > built-in default

Supported environment variables are:

• GIBWORK_PROFILE
• GIBWORK_ENVIRONMENT
• GIBWORK_API_URL
• GIBWORK_TIMEOUT_MS
• GIBWORK_CONFIG_FILE
• GIBWORK_KEYPAIR_PATH
• GIBWORK_PRIVATE_KEY

Custom API URLs require HTTPS. Loopback HTTP is permitted for local development; other plain-HTTP URLs require --allow-insecure-http.

Commands

gibwork config list
gibwork config get <key>
gibwork config set <key> <value>
gibwork config unset <key>

gibwork wallet address
gibwork wallet doctor

gibwork task create [options]
gibwork task list [--page N] [--limit N] [--all]
gibwork task get <task-id>
gibwork task available [--page N] [--limit N]
gibwork task update <task-id> [options]
gibwork task refund <task-id>

gibwork submission list <task-id> [options]
gibwork submission create <task-id> --from work.json --recovery-file attempt.json
gibwork submission resume <recovery-file>
gibwork submission intent <task-id> <intent-id>
gibwork submission show <task-id> <submission-id>
gibwork submission approve <task-id> <submission-id> --amount <decimal>
gibwork submission reject <task-id> <submission-id> [options]

gibwork comment list <task-id> <submission-id>
gibwork comment create <task-id> <submission-id> [options]

gibwork mcp doctor
gibwork mcp serve [--read-only] [--state-dir <path>]
gibwork mcp install <claude|codex> [--read-only]

gibwork update --check
gibwork update [--yes]

Run gibwork <command> --help for every option.

Connect AI coding clients

The CLI includes a pinned @gibwork/mcp dependency. Installing or updating the CLI installs its matching MCP runtime. Check which clients are available and register the included runtime:

gibwork mcp doctor
gibwork --profile production mcp install claude
gibwork --profile production mcp install codex

Registration enables bounty creation and other write tools by default. Pass --read-only to register inspection tools only. The helper stores an explicit permission mode and optional profile name in the client configuration; it refuses wallet credentials and never copies key material into Claude Code or Codex settings. Running the command again replaces the existing registration.

The default registration launches gibwork mcp serve through the current Node executable and CLI entry point, so subsequent CLI updates also select the updated MCP dependency. MCP uses stdio for protocol traffic and retains its existing profile, credential, and recovery-directory behavior. Restart the client/server after updating to load the new runtime.

Registrations created by older CLI versions may still launch a separate global gibwork-mcp. Run gibwork mcp install <client> again with the same profile, scope, and permission mode to migrate that client. Registration is explicit; updating the CLI does not rewrite client configurations.

doctor reports the selected runtime's source and version compatibility. An old or unrecognized external MCP version is not ready merely because it runs. Use --executable <command> on mcp doctor or mcp install to deliberately select a separately managed runtime; it must match the supported MCP minor version and be at least the pinned patch version. Doctor checks executable readiness, not which runtime an already-running client has loaded.

gibwork task list shows an ACTIONS column containing the operations the configured wallet may perform on each task. JSON output includes the underlying canEdit, canApprove, canReject, and canRefund values.

gibwork task get <task-id> returns one bounty's complete content, reward, creator, media, and participation settings by UUID.

The REWARDED column uses each token's decimals to display human-readable token amounts. JSON output preserves the API's raw base-unit values.

Discover tasks and submit work

gibwork task available discovers work across creators using the configured wallet. It supports --page (default 1) and --limit (default 15, maximum 100). It does not support --all. Results include requirements and participation restrictions; eligibility is checked during prepare. The reward pool is the original allocation, not remaining funds. JSON asset/minimum amounts remain strings in base units; human output uses the asset's decimals.

Save the exact work and a caller-chosen UUIDv4 key in work.json:

{
  "content": "<p>Completed work: https://example.com/work</p>",
  "idempotencyKey": "e9467bf1-bf01-43f4-8dbd-71c3d624bce6"
}

gibwork --json submission create <task-id> --from work.json --recovery-file attempt.json
gibwork --json submission intent <task-id> <intent-id>
gibwork --json submission resume attempt.json

Creation saves an owner-only recovery file before requesting an intent, displays the returned participation fee, and asks for confirmation before signing. Its parent directory must already exist. An active platform wallet and eligibility are required. Use the quoted fee; the CLI does not hard-code its amount.

Alternatively, supply --content or --content-file, --idempotency-key, optional --referral, and repeated --media-id values. JSON supports optional nullable referral and mediaIds. Media IDs must refer to already-uploaded, wallet-owned media; upload is not provided. The CLI preserves content, referral, and media order exactly. --from cannot be combined with those payload flags. Input on stdin requires --yes and cannot share stdin with a private key.

Keep the recovery file: it stores the original input/key, wallet, environment, API location, and progress, without credentials or transactions. Never replace the key or edit its phase to force a retry. resume requires the original wallet/configuration and can continue a pending pre-submit attempt with another confirmation. After submit dispatch it only reads status, even when that status is still pending. Interrupted prepare reuses the exact persisted input/key. There is no automatic polling or payment retry.

The CLI locks the recovery file throughout the operation. After an abrupt process crash, a neighboring .lock file can remain. Inspect its recorded PID and verify that the process has stopped before removing that lock and resuming. Retain the recovery file itself. A persistence error after dispatch includes the known outcome/IDs; reconcile the intent before taking another financial action.

| Intent status | Meaning | | -------------------- | ----------------------------------------------------------------------------------- | | pending | Creation incomplete; resume only an attempt that has not dispatched payment. | | submitted | Settlement unresolved; read the same intent later. | | fulfilled | Fee confirmed and submission created. | | failed / expired | Resolve the attempt before explicitly choosing a new key. | | requires_review | Fee paid; operator attention required. Retain the intent/hash and do not pay again. |

Only fulfilled confirms creation. An allocated submission ID or HTTP success does not. Intent reads report creation and participation-fee settlement, not creator review or payout; submission show remains creator-facing.

Successful API responses use {ok:true,data}, with data.created and data.status. Create/resume exit 0 only for fulfilled creation (or an explicit data.cancelled result); other returned intent states exit 1. The intent command exits 0 when the read succeeds regardless of intent status. API errors retain structured details and optional raw retryAfter (seconds or HTTP date). Respect that delay before an explicit next request. Unknown submit outcomes use exit 22 and include the recovery identifiers.

View a submission

gibwork submission show <task-id> <submission-id>
gibwork --json submission show <task-id> <submission-id>

Human-readable output includes the submission content, contributor, status, rating, asset, media, and comments. Use --json to receive the complete SDK response unchanged.

Create a task from JSON

{
  "title": "Write an SDK guide",
  "content": "<p>Document the Gibwork SDK.</p>",
  "tags": ["Docs"],
  "payment": {
    "amount": "25.00"
  },
  "minSubmissionAmount": "5.00"
}

gibwork task create --from task.json

Or use flags for common fields:

gibwork task create \
  --title 'Write an SDK guide' \
  --content-file description.html \
  --tag Docs \
  --amount 25.00 \
  --min-submission 5.00

The payment mint is fixed by the CLI and supplied automatically. It cannot be changed through command options, JSON input, profiles, or environment variables.

Update the CLI

Check for a newer release or update a global npm installation:

gibwork update --check
gibwork update

The update command uses the public npm registry, asks for confirmation, and installs the exact version it checked. It does not load wallet credentials and removes Gibwork private-key variables from the npm process. Package install scripts are disabled. Pass --yes for non-interactive use.

Self-update is limited to non-linked global npm installations. Installations managed by npx, a project dependency, or another package manager must be updated through that package manager. The CLI never invokes sudo or retries with elevated privileges.

Task creation, submission creation/payment resume, refunds, approvals, and rejections require confirmation. For non-interactive automation, pass --yes. Create, refund, and approval commands prepare the transaction first and show the SDK quote before signing. The CLI submits a signed transaction only once and never retries an ambiguous submit.

Machine-readable output

Use --json for a stable envelope on stdout:

{ "ok": true, "data": { "walletAddress": "..." } }

Errors use stderr and a non-zero exit status:

{ "ok": false, "error": { "code": "CREDENTIAL_ERROR", "message": "..." } }

Prompts, warnings, and progress messages are kept on stderr. JSON output is not colored and never contains private keys, authorization headers, or serialized transactions.

Exit statuses:

| Status | Meaning | | -----: | ------------------------------------------------------------------------ | | 0 | Success | | 1 | Operational/protocol/recovery failure, or incomplete submission creation | | 2 | Invalid command or input | | 10 | Configuration or credential failure | | 20 | Gibwork API failure | | 21 | Network failure or timeout | | 22 | Ambiguous transaction submit; do not retry the intent | | 130 | Interrupted operation |

Releasing the CLI

release.json records the reviewed CLI version, skill version/source revision, MCP baseline, and SDK dependency. Update it with the canonical skill export before releasing. The private skill source is not required to build or install the CLI.

Prepare the pinned published baseline once (network access), then commit the complete release candidate and build the review artifact:

npm run test:baseline
npm run release:prepare

Baseline preparation downloads CLI 0.2.3 or reuses its retained tarball. CLI 0.2.1 is no longer available on npm; its additional legacy upgrade test runs when a retained copy is available. For offline preparation of both baselines, use npm run test:baseline -- /path/to/cli-0.2.1.tgz /path/to/cli-0.2.3.tgz. The recorded npm SHA-512 integrity is checked for both versions. Packed tests run offline in isolated homes for both clients and scopes, including upgrades from both actual packages.

Preparation requires a clean committed checkout, runs the checks and packed upgrade tests, and writes a new artifacts/release-<version>-<commit>/ directory containing the verified tarball and release-record.json. Review the record, source revision, and artifact integrity before authorizing publication.

npm run publish:npm -- artifacts/release-<version>-<commit>/release-record.json
npm run release:verify-published -- artifacts/release-<version>-<commit>/release-record.json

Publication refuses an existing npm version or a changed checkout, release contract, or tarball. It publishes the exact reviewed archive with lifecycle scripts disabled after explicitly running release gates. Direct source-directory publication is rejected. Registry verification downloads the deployed tarball and compares its integrity, skill contract, and payload hashes with the review record, then reruns the isolated upgrade test using the downloaded package. A registry verification failure after publish does not roll back publication; reconcile the registry state before choosing a new patch release.

After a corrected release reaches npm, users run gibwork update followed by gibwork skills update codex (or claude, with the original scope). CLI updates do not silently replace installed instructions.