Kernel CLI

The Kernel CLI is a fast, friendly command‑line interface for Kernel — the platform that provides sandboxed, ready‑to‑use Chrome browsers for browser automations and web agents.

Sign up at kernel.sh and read the docs.

What's Kernel?

Kernel provides sandboxed, ready-to-use Chrome browsers for browser automations and web agents. This CLI helps you deploy apps, run actions, manage browsers, and access live views.

What you can do with the CLI

• Create new Kernel applications from templates
• Deploy and version apps to Kernel
• Invoke app actions (sync or async) and stream logs
• Create, list, view, and delete managed browser sessions
• Get a live view URL for visual monitoring and remote control

Installation

Install the Kernel CLI using your favorite package manager:

# Using brew (recommended)
brew install onkernel/tap/kernel

# Using pnpm
pnpm install -g @onkernel/cli

# Using npm
npm install -g @onkernel/cli

Verify the installation:

which kernel
kernel --version

Quick Start

1. Create a new Kernel app:

   kernel create

2. Authenticate with Kernel:

   kernel login

3. Deploy your app:

   kernel deploy index.ts

4. Invoke your app:

   kernel invoke my-app action-name --payload '{"key": "value"}'

Authentication

OAuth 2.0 (Recommended)

The easiest way to authenticate is using OAuth:

kernel login

This opens your browser to complete the authentication flow. Choose organization-wide access or restrict the login to one project. Your credentials are securely stored, automatically refreshed, and retain the selected scope until you log in again.

API Key

You can also authenticate using an API key:

export KERNEL_API_KEY=<YOUR_API_KEY>

Create an API key from the Kernel dashboard.

Commands Reference

Global Flags

• --version, -v - Print the CLI version
• --no-color - Disable color output
• --log-level <level> - Set log level (trace, debug, info, warn, error, fatal, print)
• --project <id-or-name> - Scope requests to a project by ID or exact name (or set KERNEL_PROJECT). A non-empty flag overrides the environment variable. The selector is sent to the API as X-Kernel-Project, without a client-side project lookup. Project-scoped API keys and OAuth tokens cannot switch projects.

JSON Output

Many commands support JSON output for scripting and automation. Use --output json or -o json to get machine-readable output:

# Get browser session details as JSON
kernel browsers create -o json

# List apps as JSON
kernel app list -o json

# Deploy with JSONL streaming output (one JSON object per line)
kernel deploy index.ts -o json

Commands with JSON output support:

• Browsers: create, list, get, view
• Browser Pools: create, list, get, update, acquire
• Profiles: create, list, get, update
• Extensions: upload, list
• Proxies: create, list, get, update, check
• API Keys: create, list, get, update, rotate
• Auth Connections: timeline
• Vaults: create, list, get, credentials create/update, items list/get/events/invoke (including collect, fill, and prepare_checkout), wallets create/payment-methods, cards create/update (display-safe public fields only)
• Projects: update
• Org: limits get/set
• Apps: list, history
• Deploy: deploy (JSONL streaming), history
• Invoke: invoke (JSONL streaming), history
• Browser Sub-commands: replays list/start, process exec/spawn, fs file-info/list-files, webmcp list, webmcp custom-tools list/add (webmcp invoke always prints JSON output)
• Browser NDJSON streaming: telemetry stream

Search

Search commands always return the full API response as JSON, including results, warnings, provider attempts, usage, and expiry. They use the normal API key or OAuth authentication and global --project scope. Your organization must have Search API access enabled.

# Discover currently configured providers and capabilities
kernel search providers

# Automatic routing
kernel search "Playwright browser automation" --max-results 5

# Retrieve a retained result without another provider call or search charge
kernel search get srch_01jsearchresult

# Use portable filters or other advanced request fields
kernel search --request '{"query":"browser automation","include_domains":["example.com"],"strict_params":true}'

• --max-results accepts 1–100; the API may clamp it to the provider cap.
• --request accepts the complete Search API JSON object, including max_results, typed strategies (auto, pinned, or fallback), portable filters, content, include_raw, date/locale filters, and provider-specific options. It cannot be combined with a positional query, --provider, or --max-results. Provider-specific and advanced request validation is performed by the API.
• Create requests are not automatically retried, to avoid duplicate billable searches after an ambiguous failure. If a request fails ambiguously, use search get only when the API returned a retained search ID.
• Retained searches return 404 when missing, expired, or inaccessible. Deferred content retrieval is not exposed because it is reserved but unavailable in the current API contract.
• To search for a literal query equal to a subcommand name (get or providers), use --request '{"query":"providers"}'.

Authentication

• kernel login [--force] - Login via OAuth 2.0
• kernel logout - Clear stored credentials
• kernel auth - Check authentication status

App Creation

• --name <name>, -n - Name of the application
• --language <language>, -l - Sepecify app language: typescript, or python
• --template <template>, -t - Template to use:
  • sample-app - Basic template with Playwright integration
  • captcha-solver - Template demonstrating Kernel's auto-CAPTCHA solver
  • stagehand - Template with Stagehand SDK (TypeScript only)
  • browser-use - Template with Browser Use SDK (Python only)
  • anthropic-computer-use - Anthropic Computer Use prompt loop
  • openai-computer-use - OpenAI Computer Use Agent sample
  • gemini-computer-use - Implements a Gemini computer use agent (TypeScript only)
  • openagi-computer-use - OpenAGI Lux computer-use models (Python only)
  • claude-agent-sdk - Claude Agent SDK browser automation agent

App Deployment

• kernel deploy <file> - Deploy an app to Kernel

  • --version <version> - Specify app version (default: latest)
  • --force - Allow overwriting existing version
  • --env <KEY=VALUE>, -e - Set environment variables (can be used multiple times)
  • --env-file <file> - Load environment variables from file (can be used multiple times)
  • --output json, -o json - Output JSONL (one JSON object per line for each event)

• kernel deploy logs <deployment_id> - Stream logs for a deployment

  • --follow, -f - Follow logs in real-time (stream continuously)
  • --since, -s - How far back to retrieve logs. Duration formats: ns, us, ms, s, m, h (e.g., 5m, 2h, 1h30m). Timestamps also supported: 2006-01-02, 2006-01-02T15:04, 2006-01-02T15:04:05, 2006-01-02T15:04:05.000
  • --with-timestamps, -t - Include timestamps in each log line

• kernel deploy history [app_name] - Show deployment history

  • --limit <n> - Max deployments to return (default: 100; 0 = all)
  • --output json, -o json - Output raw JSON array

App Management

• kernel invoke <app> <action> - Run an app action

  • --version <version>, -v - Specify app version (default: latest)
  • --payload <json>, -p - JSON payload for the action
  • --payload-file <path>, -f - Read JSON payload from a file (use - for stdin)
  • --sync, -s - Invoke synchronously (timeout after 60s)
  • --output json, -o json - Output JSONL (one JSON object per line for each event)

• kernel app list - List deployed apps

  • --name <app_name> - Filter by app name
  • --version <version> - Filter by version
  • --output json, -o json - Output raw JSON array

• kernel app history <app_name> - Show deployment history for an app

  • --limit <n> - Max deployments to return (default: 100; 0 = all)
  • --output json, -o json - Output raw JSON array

Logs

• kernel logs <app_name> - View app logs
  • --version <version> - Specify app version (default: latest)
  • --follow, -f - Follow logs in real-time
  • --since <time>, -s - How far back to retrieve logs (e.g., 5m, 1h)
  • --with-timestamps - Include timestamps in log output

Browser Management

• kernel browsers list - List running browsers
  • --query <q> - Search by name, session ID, profile ID, proxy ID, or pool name
  • --region us-east|eu-west|ap-southeast - Filter by geographic region; omit to list sessions in all regions
  • --tag <KEY=VALUE> - Filter by tag, repeatable; a session must match every pair
  • --output json, -o json - Output raw JSON array
• kernel browsers create - Create a new browser session
  • -s, --stealth - Launch browser in stealth mode to avoid detection
  • -H, --headless - Launch browser without GUI access
  • --kiosk - Launch browser in kiosk mode
  • --region us-east|eu-west|ap-southeast - Geographic region for the session. Fixed once the session is created; requires a Start-Up or Enterprise plan and defaults to us-east.
  • --private-host <host> - Destination the browser reaches directly through the session's own network instead of Kernel-managed egress, for private hosts on a VPN or tunnel the session joins (repeatable or comma-separated, max 32). Accepts hostname patterns (*.example.ts.net), IPs (10.1.30.63, [fd00::1]), and private CIDRs (100.64.0.0/10). Replaces the default private ranges (RFC1918, 100.64.0.0/10, fc00::/7); omit to keep them. Fixed once the session is created. Unrelated to a proxy's --bypass-host, which only chooses between upstream proxy and Kernel-managed direct egress.
  • --proxy-route '<host>[,<host>...]=<proxy>' - Route matching browser requests through a selected proxy (repeatable, max 10 routes with 1–50 hosts each). Example: --proxy-route 'api.ipify.org,*.ipify.org=name:my-dc-proxy'. The proxy is an ID by default; use id:<id> or name:<name> explicitly. Exact hostnames beat wildcards; longer wildcard suffixes beat shorter ones. *.example.com matches subdomains, not example.com. Matching ignores case and ports. Unmatched hosts use --proxy-* or default egress, while --start-url uses the top-level proxy during setup. Routes are create-only and are not available on pool sessions.
  • --start-url <url> - Initial page to open on launch
  • --proxy-id <id> / --proxy-name <name> - Use that proxy for the session regardless of stealth (mutually exclusive with each other and with --proxy-mode)
  • --proxy-mode direct|default - Egress mode instead of a selected proxy: direct for no proxy regardless of stealth, default for the stealth-derived default (Kernel's stealth proxy with --stealth, direct egress otherwise). Omit all proxy flags to get the default.
  • --name <name> - Optional unique name for the session (used to find it later by name; can be changed with browsers update --name)
  • --tag <KEY=VALUE> - Set a tag on the session, repeatable; up to 50 pairs
  • --vault <id-or-name> - Attach a project-owned vault at creation (repeatable, max 20). Uses the API's effective project unless --project or KERNEL_PROJECT selects one. Cannot be combined with pool flags, even with --yes; vault bindings cannot be added to existing sessions.
  • --pool-id <id> - Acquire a browser from the specified pool (mutually exclusive with --pool-name; ignores other session flags). --name/--tag still apply to the acquired session.
  • --pool-name <name> - Acquire a browser from the pool name (mutually exclusive with --pool-id; ignores other session flags)
  • --telemetry=all - Enable telemetry for all categories
  • --telemetry=off - Disable telemetry
  • --telemetry=<list> - Per-category config, e.g. --telemetry=network=on,page=off
  • --telemetry-export-otlp <id-or-name> - Export captured telemetry over OTLP to one of the org's configured destinations. Implies --telemetry=all when --telemetry is not set, since export requires capture. Use --telemetry-export-otlp=off to disable export.
  • --chrome-policy <json> - Custom Chrome enterprise policy as a JSON object. Kernel-managed policies (extensions, proxy, automation) are rejected server-side.
  • --chrome-policy-file <path> - Read the Chrome enterprise policy from a file (use - for stdin). Mutually exclusive with --chrome-policy.
  • --output json, -o json - Output raw JSON object
  • Note: When a pool is specified, omit other session configuration flags—pool settings determine profile, proxy, viewport, etc.
• kernel browsers delete <id-or-name> - Delete a browser by ID or name
• kernel browsers view <id-or-name> - Get live view URL for a browser by ID or name
  • --output json, -o json - Output JSON with liveViewUrl
• kernel browsers get <id-or-name> - Get detailed browser session info by ID or name
  • --output json, -o json - Output raw JSON object
• kernel browsers update <id-or-name> - Update a running browser session by ID or name
  • --name <name> - Set a new unique name for the session (mutually exclusive with --clear-name)
  • --clear-name - Clear the session name
  • --tag <KEY=VALUE> - Set a tag, repeatable; up to 50 pairs. Replaces the entire tag set (not merged); mutually exclusive with --clear-tags
  • --clear-tags - Remove all tags from the session
  • --telemetry=all - Enable telemetry for all categories
  • --telemetry=off - Disable telemetry
  • --telemetry=<list> - Per-category config, e.g. --telemetry=network=on,page=off
  • --proxy-id <id> / --proxy-name <name> - Switch the session to that proxy regardless of stealth (mutually exclusive with each other and with --proxy-mode)
  • --proxy-mode direct|default - Change egress mode: direct for no proxy regardless of stealth, default to restore the browser default after using a selected proxy. Changing the proxy does not change stealth or CAPTCHA solver behavior.
  • --clear-proxy - Drop the selected proxy and restore the browser default (same as --proxy-mode=default)
  • --disable-default-proxy - Connect directly instead of through the default stealth proxy (same as --proxy-mode=direct); use --disable-default-proxy=false to restore the default
  • --output json, -o json - Output raw JSON object
• kernel browsers curl <id> <url> - Make HTTP requests through a browser session's Chrome network stack
  • -X, --request <method> - HTTP method (default: GET; defaults to POST when --data is set)
  • -H, --header <header> - HTTP header, repeatable ("Key: Value" format)
  • -d, --data <body> - Request body
  • --data-file <path> - Read request body from file
  • --max-time <seconds> - Maximum time allowed for the request (default: 30)
  • -o, --output <path> - Write response body to file
  • -I, --head - Fetch headers only
  • -i, --include - Include response headers in output
  • -D, --dump-header <path> - Write received headers to file (use - for stdout)
  • -w, --write-out <format> - Output text after completion; supports %{http_code}, %{response_code}, %{time_total}, and %{size_download}
  • -f, --fail - Fail with no body output on HTTP errors
  • -s, --silent - Suppress progress output
  • Note: redirects are followed automatically by Chromium.

Vaults

Vault commands collect user credentials and manage payment credentials; fill does not submit website forms.

User credentials

Create a vault for the end user, attach it when creating a browser, then navigate to the sensitive form. Define the observed fields in the website's natural top-to-bottom order; the collection form renders this array order unchanged. Add optional non-secret labels for human-readable form text; stable names remain the state, update, and fill keys. Omit values for user collection:

kernel vaults create --name user-vault
kernel browsers create --vault user-vault
kernel vaults credentials create user-vault login --spec-file - <<'JSON'
{"description":"Hacker News","fields":[{"name":"username","label":"Username","type":"text","required":true,"sensitive":false},{"name":"password","label":"Password","type":"password","required":true,"sensitive":true}]}
JSON
kernel vaults items get user-vault login --wait 60 -o json
kernel vaults items invoke user-vault login fill --spec-file - <<'JSON'
{"browser_id":"<browser-id>","fields":[{"field":"username","selector":"#username"},{"field":"password","selector":"#password"}]}
JSON

Present the returned collection URL to the user before waiting for ready. It is a bearer credential: share it only with that user. Readiness means required values are populated, not that login succeeded. fill requires an already-open page and never navigates or submits it. Optional page_url selects the exact page; cards require it. Do not automatically retry failed/unknown fills or fall back to aliases.

Use credentials update <vault> <key> --version <version> --spec-file changes.json with a spec such as {"fields":{"password":{"value":"replacement"}}}. Keep actual secrets in protected files or stdin, never shell arguments. Omission preserves values; null or an empty string clears supported fields, including required text/email/password fields (returning them to pending collection). The form still requires nonempty required inputs. Field definitions cannot change. Stale versions fail, without retries. items invoke <vault> <key> collect reopens the full form without clearing values; compare versions to observe edits to already-ready items. When an update is bound to an earlier read, also pass --expected-item-id <id> to reject a replacement item at the same key. Neither precondition is refreshed automatically.

Do not use credential items to store, collect, or fill credit card data, including card numbers (PANs), security codes (CVV/CVC), or expiration dates. Use wallet and card item types for credit cards and payment checkout instead.

Set description to the recognizable site name only, such as Hacker News, not Hacker News sign-in credentials. Set sensitive: false explicitly for ordinary usernames and email addresses. Reserve sensitive: true for passwords, API tokens, and TOTP seeds; the omitted default remains true for safety.

Types are text, email, password, and totp. TOTP seeds must be provided through create/update, never the form; only generated codes enter the browser. Unrestricted browser access can read filled values. CLI JSON output retains explicitly non-sensitive text/email values, definitions, version, and has_value. Sensitive values and TOTP seeds are omitted. Credential spec input is capped at 128 KiB; write errors are redacted.

Vault names, item keys, and project ownership are immutable. Optionally select a project with --project <id-or-name> or KERNEL_PROJECT; otherwise, the API resolves the project from your credentials and its defaults (the default project for org-wide credentials, not all projects). Ownership is assigned from that scope, not a project_id body field. Project-scoped credentials cannot switch projects.

Command reference

| Command | Purpose / flags | | --- | --- | | kernel vaults create --name <name> | Create or retrieve the vault with that immutable name | | kernel vaults list | --limit 1..100 (default 20), --offset; JSON includes vaults and optional next_offset | | kernel vaults get <vault> | Get by ID or name | | kernel vaults delete <vault> | Invalidate the vault and all its items; --yes skips confirmation | | kernel vaults wallets create <vault> <key> --provider link\|agentcard --spec '<json>' | Connect/enroll a wallet using its provider's spec; --open opens a returned HTTPS action URL | | kernel vaults wallets payment-methods <vault> <key> | Fetch advertised live payment methods; JSON is the item with expanded.payment_methods | | kernel vaults cards create <vault> <key> --provider link\|agentcard --spec '<json>' | Create a card request; never implicitly authorize Link | | kernel vaults cards update <vault> <key> --provider link\|agentcard --spec '<json>' | Update a card spec; pending issuance preserves omitted optional fields, and the API enforces state/provider constraints | | kernel vaults items list <vault> | List item keys, types, providers, status, and required actions | | kernel vaults items get <vault> <key> | Inspect state/actions/returned AgentCard aliases and copyable operation commands; --wait 0..60, --expand payment_methods, --open | | kernel vaults items invoke <vault> <key> <operation> | GET the item, then POST an advertised operation; authorize --open opens a returned HTTPS action; prepare_checkout --params '<json>' prepares an unused AgentCard card for Square Pay; fill --params '<json>' fills checkout or login fields; collect --open opens a credential item's hosted form | | kernel vaults items events <vault> <key> | Read ordered audit events; --after <event-id>, --wait 0..60 | | kernel vaults items delete <vault> <key> | Invalidate an item; --yes skips confirmation |

<vault> accepts an ID or name. <key> is the immutable item key within that vault, not its generated item ID. Names and keys use letters, digits, dots, underscores, and hyphens (1–255 characters; not . or ..). All commands except delete support -o json. JSON preserves field presence and API-returned AgentCard aliases, while omitting unknown fields, opaque metadata, and unrecognized event data. Human output labels aliases as non-secret checkout values and distinguishes card readiness from checkout authorization/payment outcomes. Link cards do not expose aliases or support egress substitution; browser checkout uses only fill. Action and approval URLs print in full on separate lines, without table truncation. Most API failures use the CLI's standard error formatter. Wallet creation and provider config commands withhold response/transport details to prevent credential echoes; HTTP status remains visible. vaults delete and vaults items delete treat HTTP 404 as success and print Deleted or not found, whether the missing object is the project, vault, or item. Other API errors still return a nonzero exit status.

Provider specifications: wallet creation and card creation/update require --provider and --spec '<json>'. Supply only the spec object, not a {type, spec} envelope. The command sets the item type and injects provider; if JSON also contains provider, it must match. Other values are forwarded unchanged, including optional fields, without defaults or normalization. The API validates the provider-specific schema. Each command's --help includes its raw TypeScript-style types, which must stay in sync with the API spec.

• Link wallet: supply authorization: {method: "oauth", client: {type: "kernel_managed"}}.
• AgentCard wallet: use {} to enroll, or supply user_id for a user enrolled in the same organization and provider configuration.
• Link card: include the required fields shown in help. Optional line_items, totals, metadata, and expires_at are supported through JSON.
• AgentCard card: uses merchant, not Link's merchant_name. Its optional card_id selects a vaulted card; otherwise the cardholder selects one at approval.

cards update replaces the spec for requested cards. Pending issuance updates preserve omitted optional fields; explicit empty lists clear them. Wallet/provider bindings and unsupported fields cannot change after authorization starts. Checkout cards can be edited between authorizations. An uncertain update enters recovery_required and must not be retried. Identical card creation returns its existing state without polling, reauthorizing, or resetting recovery. Permitted checkout domains remain provider-assigned. Neither command submits a merchant payment.

Provider configurations and imported grants

Provider configurations are organization-owned and shared across projects. Creating, updating, or deleting one requires organization-scoped authentication; selecting --project does not elevate a project-scoped API key. Existing Kernel-managed wallet commands remain unchanged.

| Command | Purpose | | --- | --- | | kernel vault-provider-configs create --name <name> --provider link\|agentcard --credentials-file <path\|-> | Register client credentials; file JSON contains client_id and client_secret strings | | kernel vault-provider-configs list | --limit 1..100, --offset; JSON includes vault_provider_configs and optional next_offset | | kernel vault-provider-configs get <id-or-name> | Show public metadata (show is an alias); AgentCard test_mode is introspected, not selectable | | kernel vault-provider-configs update <id-or-name> | --name renames; --credentials-file rotates using a JSON object containing only client_secret | | kernel vault-provider-configs delete <id-or-name> | Delete only when no non-deleted items reference it; --yes skips confirmation |

Config commands support -o json except delete. Secrets never appear in list/get/write output. Omitted update fields stay unchanged. Provider and client ID are immutable; rotation must preserve identity and mode and affects every bound wallet. Renaming preserves the config ID and wallet bindings. Duplicate config creation returns a conflict, not credential replacement. Deletion does not delete the external client or revoke unrelated grants.

Use protected credential files or pipe directly from your secret manager with --credentials-file -. Never put secrets in shell arguments, --spec, or command examples. For an existing protected file:

kernel vault-provider-configs create --name checkout-client --provider agentcard \
  --credentials-file /secure/provider-client.json
kernel vaults wallets create checkout wallet-1 --provider agentcard --spec '{}' \
  --provider-config-name checkout-client --open

Wallet creation accepts either --provider-config-id or --provider-config-name, not both. Alternatively, AgentCard accepts provider_config: {id: ...} or {name: ...} in its spec. Do not combine a spec reference with selection flags. Bindings are immutable and responses return the resolved ID. Omitting selection preserves Kernel-managed credentials.

Link config credentials and wallet grants are different inputs. The config stores the OAuth client credentials. Your backend must complete Link OAuth and obtain a currently valid access and refresh token pair from the same grant before importing a wallet. After successful import, stop refreshing that grant in your backend: Kernel owns subsequent refresh-token rotation.

kernel vault-provider-configs create --name link-client --provider link \
  --credentials-file /secure/link-client.json
kernel vaults wallets create checkout imported-wallet --provider link --spec '{}' \
  --provider-config-name link-client --tokens-file /secure/link-grant.json

The protected grant file must contain only access_token and refresh_token JSON string fields; --tokens-file - reads the same object from stdin. With Link selection flags, omit spec.authorization. Alternatively, set authorization.method to oauth and its client to {type: "customer_managed", provider_config: {id: ...}} in --spec, still using --tokens-file. Tokens are never accepted in --spec or returned in display output.

Repeating wallet creation never replaces an imported grant. If it becomes degraded, complete fresh OAuth in your backend and import a new wallet key for new work only. This does not rebind existing cards or resolve old payments. Retain old items while reconciling uncertain payments; do not repeat an uncertain payment through the new wallet. There is no in-place imported-wallet reauthorization.

recovery_required means unresolved, not declined or expired. It stops server-side waiting. Do not retry, delete, or replace the original operation. Reconcile with the provider or support; there is no reset or caller-asserted reconciliation endpoint. Unresolved child cards can block wallet and vault deletion. Time passing or deletion is not evidence of non-execution.

Link checkout preparation

Link OAuth, user approval, and provider-issued single-use card issuance precede browser checkout. Issued Link cards use only the advertised vault-item fill operation for checkout fields.

1. Create/select a vault in the effective project. Connect the wallet in the provider's UI:

   kernel vaults create --name checkout
   kernel vaults wallets create checkout wallet-1 --provider link \
     --spec '{"authorization":{"method":"oauth","client":{"type":"kernel_managed"}}}' --open
   kernel vaults items get checkout wallet-1 --wait 60

2. Once connected, list methods and explicitly choose a returned ID:

   kernel vaults wallets payment-methods checkout wallet-1
   # Equivalent: kernel vaults items get checkout wallet-1 --expand payment_methods
   kernel vaults cards create checkout order-1 --provider link --spec '{
     "wallet": "wallet-1",
     "payment_method_id": "<returned-id>",
     "amount": 1234,
     "currency": "usd",
     "merchant_name": "Example Shop",
     "merchant_url": "https://shop.example",
     "context": "Purchase the selected office supplies from Example Shop for the approved order, with a total spending limit of 1234 minor currency units."
   }'

3. After explicit user approval, authorize only if the item advertises it. Follow the returned approval action, then observe:

   kernel vaults items get checkout order-1
   kernel vaults items invoke checkout order-1 authorize --open
   kernel vaults items get checkout order-1 --wait 60

4. When ready, attach the same vault to a new browser, navigate to checkout, and use the advertised fill operation below. Respect returned permitted domains:

   kernel browsers create --vault checkout

5. Observe outcomes independently of merchant checkout submission:

   kernel vaults items get checkout order-1
   kernel vaults items events checkout order-1
   kernel vaults items events checkout order-1 --after <last-event-id> --wait 60

AgentCard checkout preparation

For a separate AgentCard flow, create a vault and complete the wallet enrollment action:

kernel vaults create --name agentcard-checkout
kernel vaults wallets create agentcard-checkout wallet-1 --provider agentcard --spec '{}' --open
kernel vaults items get agentcard-checkout wallet-1 --wait 60

Once the wallet is connected, create the card request:

kernel vaults cards create agentcard-checkout order-1 --provider agentcard --spec '{
  "wallet": "wallet-1",
  "merchant": "Example Shop",
  "amount": 1234,
  "currency": "usd"
}'
kernel browsers create --vault agentcard-checkout

AgentCard authorizes at checkout and does not currently advertise authorize. To select a vaulted card in advance, inspect wallets payment-methods and include its ID as card_id in the card spec. Otherwise, the cardholder selects a card at approval. AgentCard-only state.aliases support egress substitution with checkout hold, approval, and replay in a browser with the vault attached. This is not a fallback after Link fill. A reusable card being ready does not mean the last payment succeeded.

Invoking item operations

items get displays every available_operations entry's type and description, plus an items invoke command retaining the selected project (replace <json> for fill or prepare_checkout). Read the description and follow its approval requirements before invoking. Required user actions (OAuth, enrollment, MFA, spend approval) appear separately; they are not operations to invoke through this endpoint.

items invoke fetches the item again and calls POST /vaults/{id_or_name}/items/{key}/operations only if the requested operation is still advertised. The API controls availability. The CLI additionally refuses invocation and opening actions in recovery_required, even if a stale action or operation was returned.

authorize sends {"type":"authorize"} without --params and returns the updated item, possibly with a required user action. collect is also parameterless and returns a credential collection URL. --open is supported for authorize, collect, and prepare_checkout. The API spec also accepts fill and prepare_checkout, with their inputs in --params or --spec-file <path|-> (mutually exclusive, maximum 128 KiB). The positional operation supplies type; including type in either input is rejected. Parameters must be a JSON object without unknown or duplicate properties. There is no operation --spec flag; wallet/card --spec flags remain unchanged. New parameterless operations can still be invoked by name when advertised.

Prepare an AgentCard checkout

For an unused AgentCard card, invoke prepare_checkout only when advertised:

kernel vaults items invoke user-123 order-1 prepare_checkout --params '{"checkout":{"browser_id":"browser-session-id","merchant_origin":"https://shop.example","environment":"production"}}' --open
kernel vaults items get user-123 order-1 --wait 60 -o json

--spec-file <path|-> accepts the same JSON. browser_id is the active session with this vault attached. merchant_origin is the canonical HTTPS origin of the top-level merchant document, not a processor iframe; HTTP localhost is allowed for tests.

Optional psp selects the tokenization processor: square, braintree, worldpay, bambora, or mercado_pago. Omit it for Square; non-Square processors require multi-processor preparation enablement. environment is production, sandbox, or shared: use production or sandbox for Square, Braintree and Worldpay, and shared for Bambora and Mercado Pago. Shared endpoints do not establish test mode; merchant credentials and configuration determine processor test mode, independently of the AgentCard credential mode.

Keep the approval page open. Poll until the item's status is ready_to_submit, then submit native Pay before state.preparation.expires_at. Readiness lasts at most 30 seconds, and polling does not extend it. The CLI displays the preparation ID, status, browser, origin, environment, processor, approval URL, and submission deadline.

Each preparation is single-use, including after failure or expiry. A preparation marked consumed has been claimed; it does not prove the payment settled or succeeded. Do not automatically retry or switch checkout paths after an uncertain result.

Fill browser fields

Fill supports credential items and ready Link cards when advertised by the API, not AgentCard. Both use the same execution and outcome handling. Credential bindings use declared field names, including TOTP fields, and must omit format. Credentials may omit page_url only when the API can resolve a unique page. Card bindings require an exact HTTPS page_url and the card fields listed below. The vault must already be attached to the browser for fill authorization. Fill writes real stored values into the browser without returning them in the result; unrestricted browser/CDP access can read those values. It does not explicitly submit forms or click buttons, though input/change events may trigger site behavior:

kernel vaults items get checkout order-1
kernel vaults items invoke checkout order-1 fill --params '{"browser_id":"browser-session-id","page_url":"https://shop.example/checkout","fields":[{"field":"number","selector":"#card-number"},{"field":"expiration","format":"MM/YY","selector":"#expiry"},{"field":"cvc","selector":"#security-code"}],"timeout_ms":10000}' -o json

• browser_id is a browser session ID, not a reusable browser name. It is sent unchanged; the CLI does not resolve names.
• For cards, page_url is the exact current top-level HTTPS URL, including path, query, and fragment, without embedded credentials. It must match exactly one open page; no prefix/glob matching.
• fields contains 1-32 bindings in write order. Each has field and a nonempty CSS selector targeting an editable input/select or its container. The API searches the selected page and descendants, including payment iframes. Do not supply frame IDs or literal values.
• Stored card fields: number, cvc, exp_month (MM), exp_year (YYYY), billing_name, billing_line1, billing_line2, billing_city, billing_state, billing_postal_code, billing_country. Billing fields use the stored address without reformatting; request only needed fields. Missing requested billing data fails validation before browser writes.
• Combined card expiration requires format: "MM/YY" or "MM/YYYY". Other fields reject format.
• Optional timeout_ms is an integer from 1 to 30000 (default 10000), for the whole operation.

Fill returns an execution result, not an updated item. Normal output shows zero-based field indices, statuses, and error codes. -o json preserves the display-safe result shape:

{"type":"fill","status":"unknown","fields":[{"index":0,"status":"filled"},{"index":1,"status":"unknown","error_code":"timeout"},{"index":2,"status":"not_attempted"}]}

completed exits 0; failed and unknown exit nonzero with the result still on stdout, without appended error text. API/transport errors exit nonzero with a sanitized diagnostic on stderr, not a fabricated execution result. No values, selectors, DOM content, or raw browser errors are printed in fill results. Pre-write API rejections (400/403/404/409) retain HTTP status, recognized error codes, and corrective guidance, and confirm that the request wrote no fields. Inspect and correct the cause before deciding on a new fill. Transport loss and other uncertain failures retain the no-retry warning.

Fill is non-atomic: execution stops at the first failed/unknown field and earlier writes are not rolled back. filled does not mean the site retained or accepted the value; completed does not mean logged in or paid. Transport errors do not prove no writes occurred. Inspect the browser before deciding what to do next. The CLI never retries, explicitly submits website forms, or falls back to aliases. Link cards do not expose state.aliases or support egress substitution. AgentCard-only checkout aliases are a separate integration, not a recovery path after a failed or indeterminate fill.

Expansions, updates, and lifecycle

--expand takes a value, such as --expand payment_methods; it is not a boolean switch. Request only expansions advertised in available_expansions. Add -o json to read the returned expanded.payment_methods directly. Unavailable expansions return an API error.

Use cards update <vault> <key> --provider <provider> --spec '<json>' to replace the entire card spec when the API permits it. Include optional fields you want to retain; the CLI does not merge the new JSON with the existing spec.

Waits are single bounded observations, not readiness guarantees or payment retries. Pending state is returned as-is. Requests are not automatically retried by the vault commands. Never automatically retry failed, timed-out, rejected, or indeterminate payments. Inspect state/events and reconcile the outcome instead. If an AgentCard recovery state explicitly permits user-confirmed abandonment, delete that card before creating a replacement; deletion does not prove the original attempt failed. Do not pass card data, OAuth codes/tokens, ciphertext, provider secrets, or sensitive provider responses to the CLI. Complete collection, OAuth, and approval actions through the provider's returned URL/UI; no callback-code command exists.

Browser Pools

• kernel browser-pools list - List browser pools
  • --region us-east|eu-west|ap-southeast - Filter by geographic region; omit to list pools in all regions
  • --output json, -o json - Output raw JSON array
• kernel browser-pools create - Create a browser pool
  • --name <name> - Optional unique name for the pool
  • --size <n> - Number of browsers in the pool (required)
  • --fill-rate <n> - Percentage of the pool to fill per minute
  • --timeout <seconds> - Idle timeout for browsers acquired from the pool
  • --stealth, --headless, --kiosk - Default pool configuration
  • --refresh-on-profile-update - Flush idle browsers when the pool's profile is updated (requires a profile)
  • --profile-id, --profile-name, --proxy-id, --region, --start-url, --extension, --viewport, --private-host - Same semantics as kernel browsers create
  • --chrome-policy <json> / --chrome-policy-file <path> - Custom Chrome enterprise policy applied to every browser in the pool, as a JSON object or from a file (- for stdin). Same semantics as kernel browsers create.
  • --telemetry=all / --telemetry=off / --telemetry=<categories> - Telemetry applied to browsers warmed into the pool. Same semantics as kernel browsers create.
  • --output json, -o json - Output raw JSON object
• kernel browser-pools get <id-or-name> - Get pool details
  • --output json, -o json - Output raw JSON object
• kernel browser-pools update <id-or-name> - Update pool configuration
  • Same flags as create (except --region, which is fixed at creation and cannot be updated) plus --clear-profile, --clear-proxy, --clear-start-url, --clear-extensions, --clear-chrome-policy, and --clear-private-hosts for removing durable configuration. --clear-private-hosts restores the default private IP ranges. --fill-rate 0 pauses automatic filling. --discard-all-idle discards all idle browsers and refills the pool. --telemetry and private-host updates only apply to browsers warmed after the update.
  • --output json, -o json - Output raw JSON object
• kernel browser-pools delete <id-or-name> - Delete a pool
  • --force - Force delete even if browsers are leased
• kernel browser-pools acquire <id-or-name> - Acquire a browser from the pool
  • --timeout <seconds> - Acquire timeout before returning 204
  • --name <name> - Optional name for the acquired session (applies to this lease; cleared on release)
  • --tag <KEY=VALUE> - Set a tag on the acquired session, repeatable; applies to this lease
  • --telemetry=all / --telemetry=off / --telemetry=<categories> - Telemetry override for this lease only, merged onto the pool's config
  • --output json, -o json - Output raw JSON object
• kernel browser-pools release <id-or-name> - Release a browser back to the pool
  • --session-id <id> - Browser session ID to release (required)
  • --reuse - Reuse the browser instance (default: true)
• kernel browser-pools flush <id-or-name> - Destroy all idle browsers in the pool

Browser Logs

• kernel browsers logs stream <id> - Stream browser logs
  • --source <source> - Log source: "path" or "supervisor" (required)
  • --follow - Follow the log stream (default: true)
  • --path <path> - File path when source=path
  • --supervisor-process <name> - Supervisor process name when source=supervisor. Most useful value is "chromium"

Browser Replays

• kernel browsers replays list <id> - List replays for a browser
  • --output json, -o json - Output raw JSON array
• kernel browsers replays start <id> - Start a replay recording
  • --framerate <fps> - Recording framerate (fps)
  • --max-duration <seconds> - Maximum duration in seconds
  • --output json, -o json - Output raw JSON object
• kernel browsers replays stop <id> <replay-id> - Stop a replay recording
• kernel browsers replays download <id> <replay-id> - Download a replay video
  • -f, --output-file <path> - Output file path for the replay video

Browser Telemetry

Telemetry config is a sub-field of the browser session. Use browsers create or browsers update to enable, disable, or configure it, and browsers get to inspect the current state.

• Enable the default set: kernel browsers update <id> --telemetry=all
• Disable: kernel browsers update <id> --telemetry=off
• Capture specific categories: kernel browsers update <id> --telemetry=console,network (any of: console, network, page, interaction, control, connection, system, screenshot, captcha)

Per-category updates are partial — only categories you name are changed; others retain their current state. --telemetry=all and --telemetry=off reset the entire config.

Exporting telemetry

Captured telemetry can be exported over OTLP to one of the org's configured destinations with --telemetry-export-otlp <id-or-name>. A value that looks like an ID is sent as one; anything else is resolved as a destination name, which must match exactly one destination in the org.

• Capture and export: kernel browsers create --telemetry-export-otlp my-collector
• Capture without exporting: kernel browsers create --telemetry=all
• Stop exporting: --telemetry-export-otlp=off

Export is bound at session creation, so it is available on browsers create and on the managed-auth commands that create a browser (auth connections create, update, and login). A browser session keeps the destination it was created with — browsers update cannot change it — and browser pools do not support export.

Telemetry destinations

Destinations are the OTLP/HTTP endpoints sessions export to. They belong to the organization, so sessions in any project can export to them. Creating, updating, or deleting one requires organization-scoped authentication; a project-scoped API key can list, get, and select destinations but not change them.

• kernel telemetry destinations list - List OTLP destinations

  • --page <n> / --per-page <n> - Page number (1-based) and items per page (default 20)
  • --name <name> - Filter by exact destination name
  • --query <text> - Substring match against name or endpoint; IDs match by exact value

• kernel telemetry destinations get <id-or-name> - Get an OTLP destination

• kernel telemetry destinations create --name <name> --endpoint <url> - Create an OTLP destination

  • --endpoint <url> - Base OTLP/HTTP endpoint without a signal path: pass https://api.honeycomb.io, not https://api.honeycomb.io/v1/logs (required)
  • --name <name> - Destination name, unique within the organization (required)
  • --description <text> - Optional description
  • --header NAME=VALUE - Header sent with each export request, typically an ingestion key (repeatable). Values are encrypted at rest and always returned redacted, so only header names are shown

• kernel telemetry destinations update <id-or-name> - Update an OTLP destination. Sessions already exporting pick up the new values without restarting, which makes this the way to rotate credentials without interrupting export

  • --name <name> / --endpoint <url> / --description <text> - Update those fields; pass --description "" to clear it
  • --header NAME=VALUE - Add or replace a header (repeatable). Headers you do not name are left as they are
  • --remove-header NAME - Delete a header (repeatable). Removals are applied before --header is merged, so a header given to both keeps its new value

• kernel telemetry destinations delete <id-or-name> - Delete an OTLP destination. Refused while sessions are still exporting to it, or while a managed auth connection still selects it

  • -y, --yes - Skip confirmation prompt

• kernel browsers telemetry stream <id> - Stream live telemetry events (NDJSON with -o json)

  • --categories <list> - Filter by event category (console, network, page, interaction, control, connection, system, screenshot, captcha, monitor)
  • --types <list> - Filter by event type (e.g. network_response, console_error)
  • --seq <n> - Resume after sequence number N (Last-Event-ID); replays events with seq > N. Omit to stream from now.
  • --replay all - Replay buffered events on connect, starting from the oldest retained event (mutually exclusive with --seq)
  • -o, --output json - Output newline-delimited JSON envelopes
  • Default output: tab-separated <time>\t[<category>]\t<type>, e.g. 15:04:05 [network] network_response

• kernel browsers telemetry events <id> - Read historical telemetry events (paged)

  • --limit <n> - Maximum number of events per page (1-100, default 20)
  • --offset <cursor> - Pagination cursor: pass the X-Next-Offset from a previous response
  • --since <ts|dur> / --until <ts|dur> - Time window (RFC-3339 timestamp or duration like 5m). --since is ignored when --offset is set; --until still bounds the page
  • --categories <list> - Filter by event category (console, network, page, interaction, control, connection, system, screenshot, captcha, monitor); filtered server-side
  • --types <list> - Filter by event type (e.g. network_response, console_error); filtered client-side, so this walks every page in the window for complete results
  • --all - Walk every page in the window instead of just the first (ignores --offset; no next_offset is returned)
  • -o, --output json - Output { "events": [...], "next_offset": "..." } (omit next_offset when there is no next page)

Browser Process Control

• kernel browsers process exec <id> [--] [command...] - Execute a command synchronously
  • --command <cmd> - Command to execute (optional; if omitted, trailing args are executed via /bin/bash -c)
  • --args <args> - Command arguments
  • --cwd <path> - Working directory
  • --timeout <seconds> - Timeout in seconds
  • --as-user <user> - Run as user
  • --as-root - Run as root
  • --env <KEY=VALUE> - Environment variable to set for the process (repeatable)
  • --output json, -o json - Output raw JSON object
• kernel browsers process spawn <id> [--] [command...] - Execute a command asynchronously
  • --command <cmd> - Command to execute (optional; if omitted, trailing args are executed via /bin/bash -c)
  • --args <args> - Command arguments
  • --cwd <path> - Working directory
  • --timeout <seconds> - Timeout in seconds
  • --as-user <user> - Run as user
  • --as-root - Run as root
  • --env <KEY=VALUE> - Environment variable to set for the process (repeatable)
  • --allocate-tty - Allocate a pseudo-terminal (PTY) for interactive shells
  • --cols <n> - Initial terminal columns (requires --allocate-tty)
  • --rows <n> - Initial terminal rows (requires --allocate-tty)
  • --output json, -o json - Output raw JSON object
• kernel browsers process kill <id> <process-id> - Send a signal to a process
  • --signal <signal> - Signal to send: TERM, KILL, INT, HUP (default: TERM)
• kernel browsers process status <id> <process-id> - Get process status
• kernel browsers process stdin <id> <process-id> - Write to process stdin (base64)
  • --data-b64 <data> - Base64-encoded data to write to stdin (required)
• kernel browsers process stdout-stream <id> <process-id> - Stream process stdout/stderr

Browser Filesystem

• kernel browsers fs new-directory <id> - Create a new directory
  • --path <path> - Absolute directory path to create (required)
  • --mode <mode> - Directory mode (octal string)
• kernel browsers fs delete-directory <id> - Delete a directory
  • --path <path> - Absolute directory path to delete (required)
• kernel browsers fs delete-file <id> - Delete a file
  • --path <path> - Absolute file path to delete (required)
• kernel browsers fs download-dir-zip <id> - Download a directory as zip
  • --path <path> - Absolute directory path to download (required)
  • -o, --output <path> - Output zip file path
• kernel browsers fs file-info <id> - Get file or directory info
  • --path <path> - Absolute file or directory path (required)
  • --output json, -o json - Output raw JSON object
• kernel browsers fs list-files <id> - List files in a directory
  • --path <path> - Absolute directory path (required)
  • --output json, -o json - Output raw JSON array
• kernel browsers fs move <id> - Move or rename a file or directory
  • --src <path> - Absolute source path (required)
  • --dest <path> - Absolute destination path (required)
• kernel browsers fs read-file <id> - Read a file
  • --path <path> - Absolute file path (required)
  • -o, --output <path> - Output file path (optional)
• kernel browsers fs set-permissions <id> - Set file permissions or ownership
  • --path <path> - Absolute path (required)
  • --mode <mode> - File mode bits (octal string) (required)
  • --owner <user> - New owner username or UID
  • --group <group> - New group name or GID
• kernel browsers fs upload <id> - Upload one or more files
  • --file <local:remote> - Mapping local:remote (repeatable)
  • --dest-dir <path> - Destination directory for uploads
  • --paths <paths> - Local file paths to upload
• kernel browsers fs upload-zip <id> - Upload a zip and extract it
  • --zip <path> - Local zip file path (required)
  • --dest-dir <path> - Destination directory to extract to (required)
• kernel browsers fs write-file <id> - Write a file from local data
  • --path <path> - Destination absolute file path (required)
  • --mode <mode> - File mode (octal string)
  • --source <path> - Local source file path (required)

Browser Extensions

• kernel browsers extensions upload <id> <extension-path>... - Ad-hoc upload of one or more unpacked extensions to a running browser instance.

Browser Computer Controls

• kernel browsers computer click-mouse <id> - Click mouse at coordinates

  • --x <coordinate> - X coordinate (required)
  • --y <coordinate> - Y coordinate (required)
  • --num-clicks <n> - Number of clicks (default: 1)
  • --button <button> - Mouse button: left, right, middle, back, forward (default: left)
  • --click-type <type> - Click type: down, up, click (default: click)
  • --hold-key <key> - Modifier keys to hold (repeatable)

• kernel browsers computer move-mouse <id> - Move mouse to coordinates

  • --x <coordinate> - X coordinate (required)
  • --y <coordinate> - Y coordinate (required)
  • --hold-key <key> - Modifier keys to hold (repeatable)

• kernel browsers computer screenshot <id> - Capture a screenshot

  • --to <path> - Output file path for the PNG image (required)
  • --x <coordinate> - Top-left X for region capture (optional)
  • --y <coordinate> - Top-left Y for region capture (optional)
  • --width <pixels> - Region width (optional)
  • --height <pixels> - Region height (optional)

• kernel browsers computer type <id> - Type text on the browser instance

  • --text <text> - Text to type (required)
  • --delay <ms> - Delay in milliseconds between keystrokes (optional)

• kernel browsers computer press-key <id> - Press one or more keys

  • --key <key> - One X11 keysym or chord, such as Return, Ctrl+t, or Ctrl+minus (repeatable)
  • --duration <ms> - Duration to hold keys down in ms (0=tap)
  • --hold-key <key> - Modifier keys to hold (repeatable)

  Pass sequential or repeated key presses as separate --key values, for example --key BackSpace --key BackSpace. Use computer type --text to enter text instead of passing text to press-key.

• kernel browsers computer scroll <id> - Scroll the mouse wheel

  • --x <coordinate> - X coordinate (required)
  • --y <coordinate> - Y coordinate (required)
  • --delta-x <pixels> - Horizontal scroll amount (+right, -left)
  • --delta-y <pixels> - Vertical scroll amount (+down, -up)
  • --hold-key <key> - Modifier keys to hold (repeatable)

• kernel browsers computer drag-mouse <id> - Drag the mouse along a path

  • --point <x,y> - Add a point as x,y (repeatable)
  • --delay <ms> - Delay before dragging starts in ms
  • --button <button> - Mouse button: left, middle, right (default: left)
  • --hold-key <key> - Modifier keys to hold (repeatable)

Browser Playwright

• kernel browsers playwright execute <id> [code] - Execute Playwright/TypeScript code against the browser
  • --timeout <seconds> - Maximum execution time in seconds (defaults server-side)
  • If [code] is omitted, code is read from stdin

Browser REPL

• kernel browsers repl <id> [code] - Execute JavaScript in the browser's persistent REPL
  • --reset - Terminate the current REPL and start a fresh one before evaluating code
  • --timeout-sec <seconds> - Maximum execution time in seconds (default 60)
  • --image-dir <path> - Directory to save images emitted by repl.emitImage(...)
  • --json, --output json, -o json - Output the raw response
  • If [code] is omitted, code is read from stdin (--reset may be used with no code)
  • Top-level bindings persist across calls until the REPL is reset or terminated. Start with repl.help() to list the available methods
  • Expression values are ignored; emit output with repl.write(...), console methods, or repl.emitImage(...)
  • A timeout, crash, or protocol failure terminates the REPL and changes its REPL ID, discarding top-level bindings. This is unrestricted code execution inside the browser VM and is not sandboxed

Browser WebMCP

• kernel browsers webmcp list <id-or-name> - Discover native and custom tools across all browser tabs and embedded frames

  • Displays name, opaque tool reference, page URL, tab ID, and readOnlyHint annotation (- when absent)
  • --exclude-custom - Return only page-provided tools
  • --json, --output json, -o json - Output the raw response: each entry has tool_ref, nested tool metadata (name, optional title, description, inputSchema, optional outputSchema, and annotations), and source details. Custom registrations include source.custom (id, namespace) and source.target_id
  • Annotations use readOnlyHint, destructiveHint, idempotentHint, openWorldHint, consequentialHint, untrustedContentHint, and autosubmit

• kernel browsers webmcp invoke <id-or-name> --tool-ref <ref> --input '<json object>' - Invoke the exact live tool registration

  • --tool-ref <ref> - Opaque reference from webmcp list (required; do not reconstruct it from the tool name)
  • --input <json> or --input-file <path> - Required JSON object; mutually exclusive. Use --input-file - to read stdin
  • --timeout-sec <seconds> - Maximum execution time, 1-120 seconds (defaults server-side)
  • Prints the tool's output as pretty JSON on completion; tool errors and cancellations exit non-zero
  • awaiting_submission is successful but warns that a non-autosubmit declarative form was filled, not submitted. Inspect the form, obtain any required confirmation, then submit through Playwright or computer interaction instead of invoking the tool again
  • Invocations are never retried automatically. A 504 outcome_unknown error prints the code, invocation ID, and message and exits non-zero. The tool may already have had side effects; verify the outcome before invoking it again

• kernel browsers webmcp custom-tools list <id-or-name> - List all registered custom tools, even when no page currently matches

  • Displays ID, namespace, kind (page or cdp), name, and URL patterns
  • --json, --output json, -o json - Output the raw response with each definition's id, namespace, kind, match.url_patterns, and nested tool metadata

• kernel browsers webmcp custom-tools add <id-or-name> --namespace <namespace> --source-file <path> - Register a batch of custom tools

  • --source-file <path> - JavaScript source file; use - to read stdin. Must evaluate to a non-empty array of definitions with URL matchers, tool metadata, and execute functions; limited to 8,000,000 UTF-8 bytes
  • --namespace <namespace> - Required; 1-128 letters, digits, underscores, dots, or hyphens
  • --force-overwrite-namespace - Atomically replace every existing tool in the namespace. By default, existing tools are retained. Active invocations continue
  • Displays registered tools in the same format as custom-tools list; supports --json, --output json, and -o json
  • Registration is never retried automatically; check custom-tools list before retrying a failed request that may have succeeded

• kernel browsers webmcp custom-tools remove <id-or-name> <tool-id> - Remove one registered tool using its generated ct_... ID, not its tool_ref. Active invocations are not canceled

Tool references expire when their document or browser process is replaced. Annotations are untrusted page-provided hints, not enforced guarantees; tool output is also untrusted page-provided data.

kernel browsers webmcp list my-browser --json
kernel browsers webmcp invoke my-browser --tool-ref '<tool_ref>' --input '{"query":"example"}' --timeout-sec 30
kernel browsers webmcp invoke my-browser --tool-ref '<tool_ref>' --input-file input.json
kernel browsers webmcp list my-browser --exclude-custom
kernel browsers webmcp custom-tools add my-browser --namespace helpers --source-file tools.js
cat tools.js | kernel browsers webmcp custom-tools add my-browser --namespace helpers --source-file - --force-overwrite-namespace
kernel browsers webmcp custom-tools list my-browser --json
kernel browsers webmcp custom-tools remove my-browser ct_abcdefghijklmnopqrstuvwx

Profiles

• kernel profiles update <id-or-name> --name <new-name> - Rename a profile
  • --name <name> - New unique profile name (required)
  • --output json, -o json - Output raw JSON object
• kernel profiles download <id-or-name> --to <dir> - Download a profile archive
  • --to <dir> - Directory to extract the profile into (required)
  • --format <format> - Archive format to request: tar.zst (compressed, default) or tar (decompressed server-side)

Projects

• kernel projects list - List projects (up to 100 by default)
  • --limit <n> - Maximum number of projects to return (1-100, default 100)
  • --offset <n> - Number of projects to skip; table indexes match this offset
  • --output json, -o json - Output { "projects": [...], "next_offset": <n> }; next_offset is omitted on the last page
  • When more projects are available, the CLI prints the exact command to fetch the next page
• kernel projects get <id-or-name> - Show a project's details
• kernel projects update <id-or-name> - Update a project's name or status
  • --name <name> - New project name (1-255 characters; cannot contain / or %)
  • --status <status> - New project status: active or archived
  • --output json, -o json - Output raw JSON object
• kernel projects delete <id-or-name> - Soft-delete a project (must have no active resources)
• kernel projects limits get <id-or-name> - Show a project's resource limit overrides
  • --output json, -o json - Output raw JSON object
• kernel projects limits set <id-or-name> - Update a project's resource limit overrides
  • --max-concurrent-sessions <n> - Cap on concurrent browser sessions (0 removes the cap)
  • --max-concurrent-invocations <n> - Cap on concurrent invocations (0 removes the cap)
  • --max-pooled-sessions <n> - Cap on pooled browser sessions (0 removes the cap)
  • --output json, -o json - Output raw JSON object

Every <id-or-name> above is resolved by the API, so a project name works anywhere a project ID does.

Extension Management

• kernel extensions list - List all uploaded extensions, including available checksums
  • --output json, -o json - Output raw JSON array
• kernel extensions get <id-or-name> - Show extension metadata (id, name, checksum, created, size, last used)
  • --output json, -o json - Output raw JSON object
• kernel extensions upload <directory> - Upload an unpacked browser extension directory
  • --name <name> - Optional unique extension name
  • --output json, -o json - Output raw JSON object