@taptapai/cli

@taptapai/cli installs the taptapai command-line tool used to manage TapTapAI integrations:

• OpenClaw plugin: taptapai-openclaw
• Claude Code plugin: taptapai-claude-code

Install

npm install -g @taptapai/cli

Verify:

taptapai --help

Command overview

taptapai status
taptapai doctor [--fix]
taptapai sessions-list [--agent <id>]
taptapai sessions-delete --id <sessionKey|sessionId> [--agent <id>] [--dry-run]
taptapai sessions-delete --all [--agent <id>] [--dry-run] [--confirm]
taptapai setup [--restart|--no-restart] [--openclaw <path>] [--write-artifacts] [--include-dataurl]
taptapai claude-setup [--start|--no-start] [--bridge <path>] [--write-artifacts] [--include-dataurl]
taptapai claude-bridge [--bridge <path>]
taptapai rotate-credential [--restart|--no-restart] [--openclaw <path>] [--write-artifacts] [--include-dataurl]
taptapai uninstall [--purge-data] [--restart|--no-restart] [--openclaw <path>]
taptapai restart-gateway [--openclaw <path>]

OpenClaw flow

taptapai setup

Sets up OpenClaw plugin pairing:

• best-effort install/enable of taptapai-openclaw
• writes/updates ~/.openclaw/openclaw.json plugin entry
• creates or reuses local secret
• prints pair token + QR payload + terminal QR
• optionally writes pairing artifacts to disk
• optionally restarts OpenClaw gateway

taptapai setup

Notes:

• If already configured, it can reuse existing credentials or rotate them.
• In interactive mode it shows an experimental-risk acknowledgment prompt.
• In non-interactive mode, setup requires TAPTAPAI_ACCEPT_RISK=1 (or true/yes/y).

taptapai rotate-credential

Rotates credential counter $N \to N+1$ while preserving the same setup password.

taptapai rotate-credential

Notes:

• Verifies password before rotation.
• Supports non-interactive password via env vars.
• If stored token is corrupted, interactive mode can recreate credentials.

taptapai uninstall

Best-effort uninstall for OpenClaw plugin:

• disables plugin
• removes plugin entries from openclaw.json
• removes plugin install directory
• optionally purges TapTapAI local data
• optionally restarts gateway

taptapai uninstall

Also purge local data:

taptapai uninstall --purge-data

taptapai restart-gateway

Runs:

openclaw gateway restart

taptapai restart-gateway

taptapai doctor

Checks OpenClaw config for common plugin issues (legacy keys, missing/disabled entries, invalid package-key entry, missing token).

taptapai doctor

Apply safe fixes:

taptapai doctor --fix

taptapai status

Shows runtime/system status for OpenClaw integration:

• local credential presence
• OpenClaw plugin config presence/enabled state
• local gateway port reachability (default 18789)
• backend health check (/health)
• plugin-to-backend connectivity (gateway_v2_connected)

taptapai status

Claude Code flow

taptapai claude-setup

Configures Claude Code plugin pairing with its own independent secret store, then starts the bridge.

taptapai claude-setup

What it does:

• creates/reuses secret under ~/.taptapai/claude-code/secret.json
• writes plugin config to ~/.taptapai/claude-code/config.json
• prints pair token + QR payload + terminal QR
• optionally writes pairing artifacts via the shared pairing artifact writer
• prompts to start the Claude Code bridge in background (or auto-starts with --start)

This token is separate from OpenClaw plugin pairing.

Skip the bridge start (setup only):

taptapai claude-setup --no-start

Auto-start bridge without prompting:

taptapai claude-setup --start

taptapai claude-bridge

Starts the Claude Code bridge in background so your terminal can be closed.

Logs are written to:

~/.taptapai/claude-code/bridge.log

taptapai claude-bridge

Bridge discovery order:

1. --bridge <path> flag
2. TAPTAPAI_CLAUDE_BRIDGE env var
3. taptapai-claude-bridge binary in PATH
4. npx @taptapai/taptapai-claude-code fallback

Specify a custom bridge executable:

taptapai claude-bridge --bridge /usr/local/bin/taptapai-claude-bridge

Session management

Session commands operate on TapTapAI OpenClaw sessions (keys starting with taptapai:) in agent session storage.

List sessions:

taptapai sessions-list
taptapai sessions-list --agent main

Delete one session:

taptapai sessions-delete --id <sessionKey|sessionId>

Dry run delete:

taptapai sessions-delete --id <sessionKey|sessionId> --dry-run

Delete all TapTapAI sessions:

taptapai sessions-delete --all --confirm

Flags

• --openclaw <path>: path to openclaw executable (default: openclaw in PATH)
• --restart / --no-restart: force restart behavior for commands that can restart gateway
• --start / --no-start: control whether to start the bridge after claude-setup (default: prompt)
• --bridge <path>: path to taptapai-claude-bridge executable (default: discover from PATH / npx fallback)
• --write-artifacts: write pairing artifacts to disk
• --include-dataurl: include pairing.qr.dataurl.txt (implies artifacts)
• --purge-data: with uninstall, remove TapTapAI data directory
• --agent <id>: OpenClaw agent id for sessions (default main)
• --id <value>: session key or session id for sessions-delete
• --all: delete all TapTapAI sessions
• --confirm: required with --all unless --dry-run
• --dry-run: show deletion plan without deleting

Environment variables

General:

• TAPTAPAI_SETUP_PASSWORD (or TAPTAPAI_PASSWORD): non-interactive password for setup/rotation/claude-setup
• TAPTAPAI_WRITE_ARTIFACTS=1|true: enable artifact writing without --write-artifacts
• TAPTAPAI_INCLUDE_DATAURL=1|true: include QR data URL artifact when artifacts are written

OpenClaw plugin:

• TAPTAPAI_BACKEND_WS_URL (default: wss://taptapai-openclaw.gettaptap.ai/ws/openclaw/v2)
• TAPTAPAI_RELAY_URL (default: https://taptapai-openclaw.gettaptap.ai)
• TAPTAPAI_ACCEPT_RISK=1|true|yes|y (bypasses interactive setup risk confirmation)

Claude Code plugin:

• TAPTAPAI_CLAUDE_WS_URL (default: wss://taptapai-openclaw.gettaptap.ai/ws/claudecode/v2)
• TAPTAPAI_CLAUDE_BRIDGE: path to the bridge executable (overrides PATH discovery)

Data locations

OpenClaw plugin data:

• ~/.openclaw/openclaw.json
• ~/.openclaw/taptapai/secret.current.json
• ~/.openclaw/taptapai/uuid.cache.json
• ~/.openclaw/taptapai/pairing/*
• ~/.openclaw/extensions/taptapai-openclaw

Claude Code plugin data:

• ~/.taptapai/claude-code/secret.json
• ~/.taptapai/claude-code/uuid.json
• ~/.taptapai/claude-code/config.json

Pairing artifacts (currently shared location used by CLI):

• ~/.openclaw/taptapai/pairing/*

Security notes

• Pair tokens are secrets. Do not paste them in public logs/issues.
• By default, pairing artifacts are not written to disk.
• Artifact directories are created with restrictive permissions, and files are written with mode 0600.

Troubleshooting

• If taptapai is not found after global install, ensure your npm global bin directory is on PATH.
• If openclaw is not in PATH, pass --openclaw /full/path/to/openclaw.
• If setup is run in CI/non-interactive shell, set TAPTAPAI_ACCEPT_RISK=1.