clawctl

The technical control plane for Clawbrowser.
Start managed profiles, automate tabs, verify identity, stream Remote Control sessions, and expose browser tools to agents.

Setup paths  |  Quick start  |  Capabilities  |  Workflows  |  Commands  |  Troubleshooting

---

clawctl is the official command-line interface for Clawbrowser. It gives humans, scripts, and coding agents one stable entry point for browser setup, profile lifecycle, CDP automation, remote viewing, verification, screenshots, extension installation, captcha workflows, skills, and MCP tools.

What clawctl does

Area	Commands	What you use it for
Setup and update	install, update, version	Reuse or prepare the Clawbrowser runtime, refresh the CLI, and refresh agent integrations.
Configure access	config set, identity	Save a Clawbrowser API key, remember a browser binary, and confirm the backend identity for the configured key.
Manage profiles	profiles, start, status, endpoint, stop, rotate	Create identity profiles, start named browser sessions, resolve CDP endpoints, restart sessions, and stop them cleanly.
Automate pages	open, wait, state, click, click-xy, input, press, select, scroll, eval	Drive the active tab through CDP from shell scripts or agents.
Observe and debug	screenshot, doctor, debug, verify, proxy-traffic	Capture evidence, check profile discovery, validate browser state, and inspect managed proxy traffic.
Work with tabs	tabs list, tabs activate, tabs close	Enumerate and switch browser tabs without leaving the CLI.
Remote control	remote	Start a detached Remote Control session and get a dashboard URL for live viewing and interaction.
Extend the browser	extensions install, captcha, skill, mcp	Install Chrome Web Store extensions, handle captcha workflows, resolve or publish skills, and expose browser tools through MCP.

Most commands support --json for automation. Most browser commands also accept --profile NAME for a managed session or --cdp URL for an existing Chrome DevTools Protocol endpoint.

Setup paths

There are two normal ways to get clawctl on a machine.

Path	Use it when	What happens
Clawbrowser or NextBrowser desktop	You installed the desktop app and it already detects clawctl.	Use clawctl directly. The app can refresh the matching agent integration with clawctl install --agent <agent> --no-api-key-prompt in the background.
Standalone bootstrap	You are on a VPS, CI runner, server, fresh agent container, or the desktop app says clawctl is missing.	Download the small clawctl archive, then run clawctl install once so it can install or reuse the browser/runtime and write agent integration files.

If clawctl version works, skip the bootstrap archive and go straight to the quick start.

clawctl version
clawctl doctor --json

Bootstrap without the desktop app

Download the standalone clawctl archive only when no usable clawctl binary is already available. The standalone archive is the bootstrapper; browser and portable runtime payloads are downloaded or reused by clawctl install.

Important

Use a durable executable directory. Avoid extracting clawctl under /tmp, because many containers and agent environments mount /tmp with noexec.

Linux

mkdir -p ~/clawbrowser-install
cd ~/clawbrowser-install

platform="linux-amd64" # or linux-arm64
archive="clawctl-${platform}.tar.gz"
url="https://github.com/clawbrowser/clawctl/releases/latest/download/${archive}"

curl -fL --retry 3 --retry-delay 2 -o "$archive" "$url"
tar -xzf "$archive"

./clawctl-${platform}/clawctl version
./clawctl-${platform}/clawctl install --json

macOS

mkdir -p ~/clawbrowser-install
cd ~/clawbrowser-install

archive="clawctl-macos-arm64.tar.gz"
url="https://github.com/clawbrowser/clawctl/releases/latest/download/${archive}"

curl -fL --retry 3 --retry-delay 2 -o "$archive" "$url"
tar -xzf "$archive"

./clawctl-macos-arm64/clawctl version
./clawctl-macos-arm64/clawctl install --json

Windows PowerShell

$root = Join-Path $env:LOCALAPPDATA "Clawbrowser"
New-Item -ItemType Directory -Force $root | Out-Null
Set-Location $root

$archive = "clawctl-win-amd64.zip"
$url = "https://github.com/clawbrowser/clawctl/releases/latest/download/$archive"

Invoke-WebRequest -Uri $url -OutFile $archive
Expand-Archive -Force $archive .

.\clawctl-win-amd64\clawctl.exe version
.\clawctl-win-amd64\clawctl.exe install --json

Quick start

Start here when clawctl version already works:

clawctl start --profile work --url https://example.com --json
clawctl endpoint --profile work --json
clawctl verify --profile work --json

If the CLI reports that an API key is missing, get one from app.clawbrowser.ai and save it once:

clawctl config set --api-key "$CLAWBROWSER_API_KEY"
clawctl identity --json

clawctl start starts or reattaches to a managed browser profile. By default it also starts detached Remote Control streaming after the profile is ready. Use --no-remote when you only need the local CDP endpoint.

Common workflows

Start a managed browser and expose CDP

clawctl start --profile work --url https://example.com --json
clawctl status --profile work --json
clawctl endpoint --profile work --json

Use the endpoint with Playwright, Puppeteer, another CDP client, or an agent that can connect to a browser over CDP.

Create and reuse identity profiles

clawctl profiles create research --country US --json
clawctl profiles ls --json
clawctl start --profile research --url https://example.com --json

For manual proxy profiles:

export CLAWCTL_PROXY_PASSWORD="..."

clawctl profiles create vendor \
  --manual-proxy \
  --proxy-scheme socks5 \
  --proxy-host 127.0.0.1 \
  --proxy-port 1080 \
  --proxy-username user \
  --json

Drive a page from a script

clawctl open https://example.com --profile work --json
clawctl wait --profile work --load --json
clawctl state --profile work --json
clawctl screenshot --profile work --full-page --output page.png

The state command returns the current page state and element IDs. Those IDs can be passed to action commands:

clawctl click --profile work 12 --json
clawctl input --profile work 18 "hello from clawctl" --json
clawctl press --profile work Enter --json

Use an existing CDP endpoint

clawctl --cdp http://127.0.0.1:9222 state --json
clawctl --cdp http://127.0.0.1:9222 screenshot --output page.png

Start Remote Control

clawctl remote --profile work --target-url-contains example.com --ttl 15m --json

The JSON response includes the remote session ID, target tab, expiration, and dashboard_url. Use target filters when a profile has multiple tabs:

clawctl remote --profile work --target-title-contains "Dashboard" --json

Install a Chrome Web Store extension

clawctl extensions install --profile work \
  --store_url "https://chromewebstore.google.com/detail/<extension-id>" \
  --json

Expose tools to agents through MCP

clawctl mcp

The MCP server exposes lifecycle, tab, page action, screenshot, verify, and dismissal capabilities over stdio JSON-RPC.

Command reference

Run clawctl help for the full command tree and clawctl <command> --help for flags. The high-level command groups are:

Command	Purpose
`install [auto	all
update	Update clawctl, Clawbrowser runtime assets, and installed agent integration files.
config set --api-key KEY	Save the Clawbrowser API key used by managed browser commands.
config set --browser-bin PATH	Remember a local Clawbrowser executable or .app bundle.
identity	Validate the configured API key and print backend identity information.
`profiles create	ls
start	Start or reattach to a managed Clawbrowser profile.
status	Report whether a managed session is running.
endpoint	Resolve the profile's CDP endpoint.
stop	Stop a managed profile.
rotate	Restart a managed profile and return a fresh endpoint.
open, wait, state	Navigate, wait for page conditions, and inspect current page state.
click, click-xy, input, press, select, scroll, eval	Perform browser actions over CDP.
`tabs list	activate
screenshot	Capture the visible viewport or full page as PNG.
remote	Start a detached Remote Control stream for browser tabs.
verify	Open clawbrowser://verify and return structured verification status.
proxy-traffic	Report managed proxy traffic state.
doctor, debug	Inspect profile discovery, CDP readiness, and diagnostic log locations.
extensions install	Install Chrome Web Store extensions through CDP.
`captcha detect	auto
`skill list	check
mcp	Run the clawctl MCP server on stdio.
version	Print the clawctl version.

Useful global flags:

Flag	Meaning
--profile NAME	Select a named Clawbrowser profile.
--cdp URL	Use an explicit CDP endpoint instead of managed profile discovery.
--json	Shortcut for --format json.
--browser-bin PATH	Override Clawbrowser executable discovery for this command.

Configuration

The most common configuration command is:

clawctl config set --api-key "$CLAWBROWSER_API_KEY"

Other useful configuration and environment values:

Name	Use
CLAWBROWSER_API_KEY	API key source for setup scripts before saving it with config set.
CLAWBROWSER_BIN	Per-process browser executable override.
CLAWBROWSER_BIN_DIR	Directory used by install/update for the managed clawctl binary.
CLAWBROWSER_INSTALL_ROOT	Root directory for Clawbrowser install assets.
CLAWBROWSER_CACHE_DIR	Cache directory for downloaded runtime assets.
CLAWBROWSER_DATA_DIR	Data directory for installed runtime state.
CLAWCTL_PROXY_PASSWORD	Password source for manual proxy profile creation.

Prefer environment variables for secret values in scripts. Avoid passing captcha provider keys or proxy passwords directly in shell history when possible.

Releases

Standalone archives are published for Linux, macOS, and Windows:

• clawctl-linux-amd64.tar.gz
• clawctl-linux-arm64.tar.gz
• clawctl-macos-arm64.tar.gz
• clawctl-win-amd64.zip
• checksums.txt

Latest release:

https://github.com/clawbrowser/clawctl/releases/latest

Troubleshooting

clawctl says an API key is required

Save a real Clawbrowser API key first:

clawctl config set --api-key "$CLAWBROWSER_API_KEY"
clawctl identity --json

The profile is not running

Start it before using tab, page action, screenshot, or Remote Control commands:

clawctl start --profile work --json
clawctl status --profile work --json

CDP discovery fails

Run:

clawctl doctor --profile work --json
clawctl debug --json

If you are not using a managed profile, pass the endpoint explicitly:

clawctl --cdp http://127.0.0.1:9222 state --json

Remote Control opens the wrong tab

List tabs and either activate the right one or pass a target filter:

clawctl tabs list --profile work --json
clawctl tabs activate --profile work <tab-id> --json
clawctl remote --profile work --target-url-contains example.com --json

Proxy or browser verification looks wrong

Use the structured verification and traffic commands instead of guessing from a page screenshot:

clawctl verify --profile work --json
clawctl proxy-traffic --json

What this repo is

This repository publishes the standalone clawctl release binaries. It does not publish the Clawbrowser browser/runtime payloads themselves; those artifacts come from the main clawbrowser/clawbrowser release pipeline and are installed or updated by clawctl when needed.

For product documentation, use clawbrowser.ai/docs. For the browser/runtime release pipeline, use clawbrowser/clawbrowser.