waitspin

Command-line client for WaitSpin — sponsored wait-state ads for verified developer surfaces.

Product / Agent Quickstart

This quickstart is for using the public WaitSpin product as an advertiser, publisher, or agent surface. If you are validating the source repository itself, use the repository root README instead: Node 22.14.x, npm install, then npm run test:waitspin.

Before install, user registration, or Checkout, review:

• Public API and agent docs: https://waitspin.com/docs
• Agent markdown: https://waitspin.com/.well-known/agents.md
• Terms: https://waitspin.com/waitspin/terms
• Privacy: https://waitspin.com/waitspin/privacy

Refund/account-credit disclosure: unused prepaid block handling is support-reviewed. No automated account-credit balance, redemption flow, or self-serve cash refund request flow is shipped yet.

Credential-free agent demo path:

npm view waitspin version
export WAITSPIN_API_KEY=wts_demo_agent_quickstart
npx --yes waitspin market --demo --json
npx --yes waitspin bid create --demo --line "Your ad" --url https://example.com --price-per-block 500 --blocks 1 --json
npx --yes waitspin bid checkout demo_campaign_001 --demo --json
npx --yes waitspin status --all --demo --json

Done means every demo command returns ok: true, "mode": "demo", and stable demo IDs such as demo_campaign_001. This path uses static CLI fixtures and does not create an account, campaign, Stripe Checkout, install, publisher event, payout, or billable impression.

Authenticated advertiser/publisher path:

npm view waitspin version
npx --yes waitspin init --email [email protected] --key-profile control
export WAITSPIN_API_KEY=PASTE_CONTROL_KEY
waitspin bid create --line "Your ad" --url https://example.com --price-per-block 500 --blocks 1
waitspin bid checkout CAMPAIGN_ID
npx --yes waitspin init --email [email protected] --key-profile publisher-extension
read -rs WAITSPIN_API_KEY && export WAITSPIN_API_KEY && printf '\n'

# First-class VS Code-compatible user paths
code --install-extension waitspin.waitspin-vscode
cursor --install-extension waitspin.waitspin-vscode --force
devin-desktop --install-extension waitspin.waitspin-vscode --force
# Then run "WaitSpin: Connect and earn" inside the matching editor.

# Equivalent WaitSpin-managed local editor lifecycle
waitspin extension install --target cursor
waitspin extension status --target cursor
waitspin extension uninstall --target cursor
waitspin extension install --target devin
waitspin extension status --target devin
waitspin extension uninstall --target devin

# Advanced agent install for every detected all-install target
waitspin install --all --dry-run --compose-existing
waitspin install --all --compose-existing
waitspin status --all

# CLI fallback for VS Code Activity Bar/status-bar extension
waitspin extension install --target vscode
waitspin extension status --target vscode

# Or install for Claude Code statusline
waitspin claude-code install --compose-existing
waitspin claude-code status

# Or install for Antigravity CLI statusline
waitspin antigravity install --compose-existing
waitspin antigravity status

# Or install for GitHub Copilot CLI statusline
waitspin copilot install --compose-existing
waitspin copilot status

# Or install for MiMo Code shell hook
waitspin mimocode install
waitspin mimocode status

# Or install for OpenCode TUI plugin slot
waitspin opencode install
waitspin opencode status

# Or install for Grok Code CLI footer
waitspin grok install
waitspin grok status

# Or install for Qoder CLI UserPromptSubmit/Stop hooks
waitspin qoder install
waitspin qoder status

Done means the CLI returns the created campaign or install ID, and the matching waitspin bids list or waitspin status --all command can read that state back.

Commands

• waitspin init — email OTP onboarding
• waitspin bid create — create a campaign draft
• waitspin bids list — list campaigns
• waitspin bid checkout CAMPAIGN_ID — Stripe Checkout for blocks
• waitspin market — public leaderboard
• waitspin wallet connect --country US — Stripe Connect Express onboarding
• waitspin wallet status — user balance, payout, and Connect status
• waitspin wallet ledger — user delivery ledger
• waitspin wallet payout --dry-run — payout eligibility preview
• code --install-extension waitspin.waitspin-vscode — install the public VS Code Marketplace extension
• cursor --install-extension waitspin.waitspin-vscode --force — install or update the same VS Code-compatible extension in Cursor Editor Mode
• devin-desktop --install-extension waitspin.waitspin-vscode --force — install or update the same extension in Devin Desktop from Open VSX when the desktop CLI is on PATH
• WaitSpin: Connect and earn — connect the VS Code-compatible extension from inside the matching editor
• waitspin extension install --target vscode — advanced CLI fallback for VS Code extension setup
• waitspin extension status --target vscode — inspect managed VS Code extension lifecycle state
• waitspin extension uninstall --target vscode — remove the managed VS Code extension runtime and local state
• waitspin extension install --target cursor — install or update the extension through the Cursor editor CLI
• waitspin extension status --target cursor — query Cursor for the exact WaitSpin extension ID
• waitspin extension uninstall --target cursor — remove only the WaitSpin extension from Cursor
• waitspin extension install --target devin — install or update the Open VSX extension through Devin Desktop
• waitspin extension status --target devin — query Devin Desktop for the exact WaitSpin extension ID
• waitspin extension uninstall --target devin — remove only the WaitSpin extension from Devin Desktop
• On Windows, the WaitSpin lifecycle commands resolve Cursor command shims safely and auto-detect %LOCALAPPDATA%\devin\bin\devin.exe for Devin Desktop.
• waitspin install --all --dry-run — preview detected user surfaces without file changes
• waitspin install --all — install every detected all-install surface, including VS Code, Cursor, Devin Desktop, and CLI-managed targets
• waitspin status --all — aggregate lifecycle status for every user surface
• waitspin claude-code install --compose-existing — install the Claude Code statusline command
• waitspin claude-code status — inspect managed Claude Code runtime state
• waitspin claude-code uninstall — restore Claude Code statusline settings and remove managed local state
• waitspin antigravity install --compose-existing — install the Antigravity CLI statusline command
• waitspin antigravity status — inspect managed Antigravity CLI runtime state
• waitspin antigravity uninstall — restore Antigravity CLI statusline settings and remove managed local state
• waitspin copilot install --compose-existing — install the GitHub Copilot CLI statusline command
• waitspin copilot status — inspect managed GitHub Copilot CLI runtime state
• waitspin copilot uninstall — restore GitHub Copilot CLI statusline settings and remove managed local state
• waitspin mimocode install — install the MiMo Code shell hook
• waitspin mimocode status — inspect managed MiMo Code runtime state
• waitspin mimocode uninstall — remove managed MiMo Code runtime and bash hook
• waitspin opencode install — install the OpenCode TUI plugin slot
• waitspin opencode status — inspect managed OpenCode runtime state
• waitspin opencode uninstall — remove managed OpenCode runtime and plugin
• waitspin grok install — install the Grok Code CLI footer surface
• waitspin grok status — inspect managed Grok Code CLI runtime state
• waitspin grok uninstall — restore Grok Code CLI and remove managed state
• waitspin qoder install — install the Qoder CLI UserPromptSubmit/Stop hooks
• waitspin qoder status — inspect managed Qoder CLI runtime state
• waitspin qoder uninstall — remove the managed Qoder hook and local state

API base: https://api.waitspin.com

The public package manages the public target set: the status-bar-fallback extension path for VS Code, Cursor Editor Mode, and Devin Desktop through Open VSX, the Claude Code statusline command, the Antigravity CLI statusline command, the GitHub Copilot CLI statusline command, the MiMo Code shell hook, the OpenCode TUI plugin slot, the Grok Code CLI footer, and the Qoder CLI UserPromptSubmit/Stop hooks. Claude Code, Antigravity CLI, and GitHub Copilot CLI support use first-class statusLine.command paths and do not patch native binaries. MiMo Code uses a bash hook that polls the API for sponsored messages. OpenCode uses its TUI app_bottom plugin slot. Grok Code CLI uses a managed text-asset footer patch with hash-backed backup/restore and does not patch native binaries. Qoder CLI uses the official UserPromptSubmit hook with statusMessage/systemMessage plus the official Stop hook for the later visibility callback; it does not patch native binaries or npm package files.

waitspin install --all is an advanced agent command for installing every detected all-install target, including VS Code, Cursor Editor Mode, Devin Desktop, and CLI-managed targets. Install-all keeps explicit target commands as the canonical debug path, supports --dry-run, skips unsupported local tools in skipped_not_detected, reports recoverable config conflicts in skipped_conflict, and reports unexpected installer failures in failed_rollback.

Payout execution is guarded server-side. Public launch proof uses Stripe test mode with waitspin wallet payout --confirm-test-transfer; live transfers stay disabled until the operator enables the explicit live payout flags.

Native spinner patches beyond supported status surfaces, account-credit redemption, cash refund self-service, and click billing are not public paid-launch capabilities yet.

User install credentials

Use an extension API key created with --key-profile publisher-extension for user install polling/events:

npx waitspin init --email [email protected] --key-profile publisher-extension
read -rs WAITSPIN_API_KEY && export WAITSPIN_API_KEY && printf '\n'
code --install-extension waitspin.waitspin-vscode
cursor --install-extension waitspin.waitspin-vscode --force
devin-desktop --install-extension waitspin.waitspin-vscode --force
# Then run "WaitSpin: Connect and earn" inside the matching editor.
npx waitspin install --all --dry-run --compose-existing
npx waitspin install --all --compose-existing
npx waitspin status --all
npx waitspin extension install --target vscode
npx waitspin extension install --target cursor
npx waitspin extension status --target cursor
npx waitspin extension uninstall --target cursor
npx waitspin extension install --target devin
npx waitspin extension status --target devin
npx waitspin extension uninstall --target devin
npx waitspin claude-code install --compose-existing
npx waitspin antigravity install --compose-existing
npx waitspin copilot install --compose-existing
npx waitspin mimocode install
npx waitspin opencode install
npx waitspin grok install
npx waitspin qoder install

• WAITSPIN_API_KEY — temporary extension API key for CLI fallback flows
• WAITSPIN_INSTALL_ID — from waitspin extension install or waitspin claude-code install

The VS Code Marketplace extension should normally be connected through WaitSpin: Connect and earn, which stores the extension key in VS Code-compatible SecretStorage and stores the install ID in user-scoped extension state. Cursor uses the same extension ID, and Devin Desktop uses the Open VSX listing at https://open-vsx.org/extension/waitspin/waitspin-vscode. The legacy waitspin.apiKey User setting is not accepted; raw credentials never enter editor settings. Normal editor onboarding writes directly to SecretStorage, while the macOS app uses one-time target-bound bootstrap descriptors.

The Claude Code installer writes a managed statusline runtime/state under ~/.waitspin and updates ~/.claude/settings.json with a safe statusLine.command. It fails fast when an existing unmanaged statusline is present unless --compose-existing is explicitly requested and restorable.

The Antigravity CLI and GitHub Copilot CLI installers write managed runtime/state under ~/.waitspin and configure their first-class statusLine.command settings without patching native binaries. Both fail fast when an existing unmanaged statusline is present unless --compose-existing is explicitly requested and restorable.

The MiMo Code installer writes a managed runtime script under ~/.local/bin/ and a bash hook in ~/.bashrc. It polls the API for sponsored messages and displays them in the terminal.

The OpenCode installer writes a managed runtime/state under ~/.waitspin, installs a TUI plugin under ~/.config/opencode/plugins, and adds the managed entry to ~/.config/opencode/tui.json so OpenCode mounts the app_bottom slot.

The Grok Code CLI installer writes a managed runtime/state under ~/.waitspin and patches the verified OpenTUI footer text asset with a hash-backed backup so uninstall can restore the original file.

The Qoder CLI installer writes a managed hook runtime/state/cache under ~/.waitspin and adds managed UserPromptSubmit and Stop hook entries to ~/.qoder/settings.json. The hook returns dynamic sponsored copy through Qoder's systemMessage response only after fetching WaitSpin inventory; the static hook statusMessage is a generic sponsor check and is not billable by itself. A billable Qoder impression also requires a later official Qoder hook callback after the minimum visible interval.

Cline VS Code extension installs, Cursor Editor Mode, and Devin Desktop are covered by the VS Code-compatible Activity Bar/status-bar extension target. Standalone Cline CLI is not a public install target until Cline exposes an official statusline/plugin surface.

Release validation

Before advertising the public npx waitspin path, release operators should run:

npm --workspace packages/waitspin pack --dry-run --json
npm run test:waitspin:distribution
npm view waitspin version
npx --yes waitspin --help
npx --yes waitspin@latest mimocode status
npx --yes waitspin@latest opencode status
npx --yes waitspin@latest grok status
npx --yes waitspin@latest antigravity status
npx --yes waitspin@latest copilot status
npx --yes waitspin@latest qoder status