https://github.com/onkernel/cli

Kernel CLI
https://github.com/onkernel/cli

Last synced: about 1 month ago
JSON representation

Kernel CLI

• Host: GitHub
• URL: https://github.com/onkernel/cli
• Owner: onkernel
• License: apache-2.0
• Created: 2025-08-19T17:30:55.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2025-09-04T16:45:20.000Z (5 months ago)
• Last Synced: 2025-09-04T17:36:30.229Z (5 months ago)
• Language: Go
• Homepage: https://www.onkernel.com
• Size: 56.8 MB
• Stars: 3
• Watchers: 0
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  





  

  

  

  



# 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 [onkernel.com](https://www.onkernel.com/) and read the [docs](https://onkernel.com/docs/introduction).

## 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:

```bash

# 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:

```bash

which kernel

kernel --version

```

## Quick Start

1. **Create a new Kernel app:**

   ```bash

   kernel create

   ```

2. **Authenticate with Kernel:**

   ```bash

   kernel login

   ```

3. **Deploy your app:**

   ```bash

   kernel deploy index.ts

   ```

4. **Invoke your app:**

   ```bash

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

   ```

## Authentication

### OAuth 2.0 (Recommended)

The easiest way to authenticate is using OAuth:

```bash

kernel login

```

This opens your browser to complete the authentication flow. Your credentials are securely stored and automatically refreshed.

### API Key

You can also authenticate using an API key:

```bash

export KERNEL_API_KEY=

```

Create an API key from the [Kernel dashboard](https://dashboard.onkernel.com).

## Commands Reference

### Global Flags

- `--version`, `-v` - Print the CLI version

- `--no-color` - Disable color output

- `--log-level ` - Set log level (trace, debug, info, warn, error, fatal, print)

### Authentication

- `kernel login [--force]` - Login via OAuth 2.0

- `kernel logout` - Clear stored credentials

- `kernel auth` - Check authentication status

### App Creation

- `--name `, `-n` - Name of the application

- `--language `, `-l` - Sepecify app language: `typescript`, or `python`

- `--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)

  - `magnitude` - Magnitude framework sample (TypeScript only)

### App Deployment

- `kernel deploy ` - Deploy an app to Kernel

  - `--version ` - Specify app version (default: latest)

  - `--force` - Allow overwriting existing version

  - `--env `, `-e` - Set environment variables (can be used multiple times)

  - `--env-file ` - Load environment variables from file (can be used multiple times)

- `kernel deploy logs ` - 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 ` - Max deployments to return (default: 100; 0 = all)

### App Management

- `kernel invoke  ` - Run an app action

  - `--version `, `-v` - Specify app version (default: latest)

  - `--payload `, `-p` - JSON payload for the action

  - `--sync`, `-s` - Invoke synchronously (timeout after 60s)

- `kernel app list` - List deployed apps

  - `--name ` - Filter by app name

  - `--version ` - Filter by version

- `kernel app history ` - Show deployment history for an app

  - `--limit ` - Max deployments to return (default: 100; 0 = all)

### Logs

- `kernel logs ` - View app logs

  - `--version ` - Specify app version (default: latest)

  - `--follow`, `-f` - Follow logs in real-time

  - `--since `, `-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

- `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

  - `--pool-id ` - Acquire a browser from the specified pool (mutually exclusive with --pool-name; ignores other session flags)

  - `--pool-name ` - Acquire a browser from the pool name (mutually exclusive with --pool-id; ignores other session flags)

  - _Note: When a pool is specified, omit other session configuration flags—pool settings determine profile, proxy, viewport, etc._

- `kernel browsers delete ` - Delete a browser

  - `-y, --yes` - Skip confirmation prompt

- `kernel browsers view ` - Get live view URL for a browser

### Browser Pools

- `kernel browser-pools list` - List browser pools

  - `-o, --output json` - Output raw JSON response

- `kernel browser-pools create` - Create a browser pool

  - `--name ` - Optional unique name for the pool

  - `--size ` - Number of browsers in the pool (required)

  - `--fill-rate ` - Percentage of the pool to fill per minute

  - `--timeout ` - Idle timeout for browsers acquired from the pool

  - `--stealth`, `--headless`, `--kiosk` - Default pool configuration

  - `--profile-id`, `--profile-name`, `--save-changes`, `--proxy-id`, `--extension`, `--viewport` - Same semantics as `kernel browsers create`

- `kernel browser-pools get ` - Get pool details

  - `-o, --output json` - Output raw JSON response

- `kernel browser-pools update ` - Update pool configuration

  - Same flags as create plus `--discard-all-idle` to discard all idle browsers in the pool and refill at the specified fill rate

- `kernel browser-pools delete ` - Delete a pool

  - `--force` - Force delete even if browsers are leased

- `kernel browser-pools acquire ` - Acquire a browser from the pool

  - `--timeout ` - Acquire timeout before returning 204

- `kernel browser-pools release ` - Release a browser back to the pool

  - `--session-id ` - Browser session ID to release (required)

  - `--reuse` - Reuse the browser instance (default: true)

- `kernel browser-pools flush ` - Destroy all idle browsers in the pool

### Browser Logs

- `kernel browsers logs stream ` - Stream browser logs

  - `--source ` - Log source: "path" or "supervisor" (required)

  - `--follow` - Follow the log stream (default: true)

  - `--path ` - File path when source=path

  - `--supervisor-process ` - Supervisor process name when source=supervisor. Most useful value is "chromium"

### Browser Replays

- `kernel browsers replays list ` - List replays for a browser

- `kernel browsers replays start ` - Start a replay recording

  - `--framerate ` - Recording framerate (fps)

  - `--max-duration ` - Maximum duration in seconds

- `kernel browsers replays stop  ` - Stop a replay recording

- `kernel browsers replays download  ` - Download a replay video

  - `-o, --output ` - Output file path for the replay video

### Browser Process Control

- `kernel browsers process exec  [--] [command...]` - Execute a command synchronously

  - `--command ` - Command to execute (optional; if omitted, trailing args are executed via /bin/bash -c)

  - `--args ` - Command arguments

  - `--cwd ` - Working directory

  - `--timeout ` - Timeout in seconds

  - `--as-user ` - Run as user

  - `--as-root` - Run as root

- `kernel browsers process spawn  [--] [command...]` - Execute a command asynchronously

  - `--command ` - Command to execute (optional; if omitted, trailing args are executed via /bin/bash -c)

  - `--args ` - Command arguments

  - `--cwd ` - Working directory

  - `--timeout ` - Timeout in seconds

  - `--as-user ` - Run as user

  - `--as-root` - Run as root

- `kernel browsers process kill  ` - Send a signal to a process

  - `--signal ` - Signal to send: TERM, KILL, INT, HUP (default: TERM)

- `kernel browsers process status  ` - Get process status

- `kernel browsers process stdin  ` - Write to process stdin (base64)

  - `--data-b64 ` - Base64-encoded data to write to stdin (required)

- `kernel browsers process stdout-stream  ` - Stream process stdout/stderr

### Browser Filesystem

- `kernel browsers fs new-directory ` - Create a new directory

  - `--path ` - Absolute directory path to create (required)

  - `--mode ` - Directory mode (octal string)

- `kernel browsers fs delete-directory ` - Delete a directory

  - `--path ` - Absolute directory path to delete (required)

- `kernel browsers fs delete-file ` - Delete a file

  - `--path ` - Absolute file path to delete (required)

- `kernel browsers fs download-dir-zip ` - Download a directory as zip

  - `--path ` - Absolute directory path to download (required)

  - `-o, --output ` - Output zip file path

- `kernel browsers fs file-info ` - Get file or directory info

  - `--path ` - Absolute file or directory path (required)

- `kernel browsers fs list-files ` - List files in a directory

  - `--path ` - Absolute directory path (required)

- `kernel browsers fs move ` - Move or rename a file or directory

  - `--src ` - Absolute source path (required)

  - `--dest ` - Absolute destination path (required)

- `kernel browsers fs read-file ` - Read a file

  - `--path ` - Absolute file path (required)

  - `-o, --output ` - Output file path (optional)

- `kernel browsers fs set-permissions ` - Set file permissions or ownership

  - `--path ` - Absolute path (required)

  - `--mode ` - File mode bits (octal string) (required)

  - `--owner ` - New owner username or UID

  - `--group ` - New group name or GID

- `kernel browsers fs upload ` - Upload one or more files

  - `--file ` - Mapping local:remote (repeatable)

  - `--dest-dir ` - Destination directory for uploads

  - `--paths ` - Local file paths to upload

- `kernel browsers fs upload-zip ` - Upload a zip and extract it

  - `--zip ` - Local zip file path (required)

  - `--dest-dir ` - Destination directory to extract to (required)

- `kernel browsers fs write-file ` - Write a file from local data

  - `--path ` - Destination absolute file path (required)

  - `--mode ` - File mode (octal string)

  - `--source ` - Local source file path (required)

### Browser Extensions

- `kernel browsers extensions upload  ...` - Ad-hoc upload of one or more unpacked extensions to a running browser instance.

### Browser Computer Controls

- `kernel browsers computer click-mouse ` - Click mouse at coordinates

  - `--x ` - X coordinate (required)

  - `--y ` - Y coordinate (required)

  - `--num-clicks ` - Number of clicks (default: 1)

  - `--button ` - Mouse button: left, right, middle, back, forward (default: left)

  - `--click-type ` - Click type: down, up, click (default: click)

  - `--hold-key ` - Modifier keys to hold (repeatable)

- `kernel browsers computer move-mouse ` - Move mouse to coordinates

  - `--x ` - X coordinate (required)

  - `--y ` - Y coordinate (required)

  - `--hold-key ` - Modifier keys to hold (repeatable)

- `kernel browsers computer screenshot ` - Capture a screenshot

  - `--to ` - Output file path for the PNG image (required)

  - `--x ` - Top-left X for region capture (optional)

  - `--y ` - Top-left Y for region capture (optional)

  - `--width ` - Region width (optional)

  - `--height ` - Region height (optional)

- `kernel browsers computer type ` - Type text on the browser instance

  - `--text ` - Text to type (required)

  - `--delay ` - Delay in milliseconds between keystrokes (optional)

- `kernel browsers computer press-key ` - Press one or more keys

  - `--key ` - Key symbols to press (repeatable)

  - `--duration ` - Duration to hold keys down in ms (0=tap)

  - `--hold-key ` - Modifier keys to hold (repeatable)

- `kernel browsers computer scroll ` - Scroll the mouse wheel

  - `--x ` - X coordinate (required)

  - `--y ` - Y coordinate (required)

  - `--delta-x ` - Horizontal scroll amount (+right, -left)

  - `--delta-y ` - Vertical scroll amount (+down, -up)

  - `--hold-key ` - Modifier keys to hold (repeatable)

- `kernel browsers computer drag-mouse ` - Drag the mouse along a path

  - `--point ` - Add a point as x,y (repeatable)

  - `--delay ` - Delay before dragging starts in ms

  - `--button ` - Mouse button: left, middle, right (default: left)

  - `--hold-key ` - Modifier keys to hold (repeatable)

### Browser Playwright

- `kernel browsers playwright execute  [code]` - Execute Playwright/TypeScript code against the browser

  - `--timeout ` - Maximum execution time in seconds (defaults server-side)

  - If `[code]` is omitted, code is read from stdin

### Extension Management

- `kernel extensions list` - List all uploaded extensions

- `kernel extensions upload ` - Upload an unpacked browser extension directory

  - `--name ` - Optional unique extension name

- `kernel extensions download ` - Download an extension archive

  - `--to ` - Output directory (required)

- `kernel extensions download-web-store ` - Download an extension from the Chrome Web Store

  - `--to ` - Output directory (required)

  - `--os ` - Target OS: mac, win, or linux (default: linux)

- `kernel extensions delete ` - Delete an extension by ID or name

  - `-y, --yes` - Skip confirmation prompt

### Proxy Management

- `kernel proxies list` - List proxy configurations

- `kernel proxies get ` - Get a proxy configuration by ID

- `kernel proxies create` - Create a new proxy configuration

  - `--name ` - Proxy configuration name

  - `--type ` - Proxy type: datacenter, isp, residential, mobile, custom (required)

  - `--protocol ` - Protocol to use (default: https)

  - `--country ` - ISO 3166 country code or "EU" (location-based types)

  - `--city ` - City name (no spaces, e.g. sanfrancisco) (residential, mobile; requires `--country`)

  - `--state ` - Two-letter state code (residential, mobile)

  - `--zip ` - US ZIP code (residential, mobile)

  - `--asn ` - Autonomous system number (e.g., AS15169) (residential, mobile)

  - `--os ` - Operating system: windows, macos, android (residential)

  - `--carrier ` - Mobile carrier (mobile)

  - `--host ` - Proxy host (custom; required)

  - `--port ` - Proxy port (custom; required)

  - `--username ` - Username for proxy authentication (custom)

  - `--password ` - Password for proxy authentication (custom)


- `kernel proxies delete ` - Delete a proxy configuration

  - `-y, --yes` - Skip confirmation prompt

## Examples

### Create a new app

```bash

# Interactive mode (prompts for all options)

kernel create

# Create a TypeScript app with sample template

kernel create --name my-app --language typescript --template sample-app

# Create a Python app with Browser Use

kernel create --name my-scraper --language python --template browser-use

# Create a TypeScript app with Stagehand

kernel create --name my-agent --language ts --template stagehand

# Create a Python Computer Use app

kernel create --name my-cu-app --language py --template anthropic-computer-use

```

### Deploy with environment variables

```bash

# Set individual variables

kernel deploy index.ts --env API_KEY=abc123 --env DEBUG=true

# Load from .env file

kernel deploy index.ts --env-file .env

# Combine both methods

kernel deploy index.ts --env-file .env --env OVERRIDE_VAR=value

```

### Invoke with payload

```bash

# Simple invoke

kernel invoke my-scraper scrape-page

# With JSON payload

kernel invoke my-scraper scrape-page --payload '{"url": "https://example.com"}'

# Synchronous invoke (wait for completion)

kernel invoke my-scraper quick-task --sync

```

### Follow logs in real-time

```bash

# Follow logs

kernel logs my-app --follow

# Show recent logs with timestamps

kernel logs my-app --since 1h --with-timestamps

```

### Browser management

```bash

# List all browsers

kernel browsers list

# Create a new browser session

kernel browsers create

# Create a browser with a longer timeout (up to 72 hours)

kernel browsers create --timeout 3600

# Create a headless browser in stealth mode

kernel browsers create --headless --stealth

# Create a browser in kiosk mode

kernel browsers create --kiosk

# Create a browser with a profile for session state

kernel browsers create --profile-name my-profile

# Delete a browser

kernel browsers delete browser123 --yes

# Get live view URL

kernel browsers view browser123

# Stream browser logs

kernel browsers logs stream my-browser --source supervisor --follow --supervisor-process chromium

# Start a replay recording

kernel browsers replays start my-browser --framerate 30 --max-duration 300

# Execute a command in the browser VM

kernel browsers process exec my-browser -- ls -alh /tmp

# Upload files to the browser VM

kernel browsers fs upload my-browser --file "local.txt:remote.txt" --dest-dir "/tmp"

# List files in a directory

kernel browsers fs list-files my-browser --path "/tmp"

# Click the mouse at coordinates (100, 200)

kernel browsers computer click-mouse my-browser --x 100 --y 200

# Double-click the right mouse button

kernel browsers computer click-mouse my-browser --x 100 --y 200 --num-clicks 2 --button right

# Move the mouse to coordinates (500, 300)

kernel browsers computer move-mouse my-browser --x 500 --y 300

# Take a full screenshot

kernel browsers computer screenshot my-browser --to screenshot.png

# Take a screenshot of a specific region

kernel browsers computer screenshot my-browser --to region.png --x 0 --y 0 --width 800 --height 600

# Type text in the browser

kernel browsers computer type my-browser --text "Hello, World!"

# Type text with a 100ms delay between keystrokes

kernel browsers computer type my-browser --text "Slow typing..." --delay 100

```

### Playwright execution

```bash

# Execute inline Playwright (TypeScript) code

kernel browsers playwright execute my-browser 'await page.goto("https://example.com"); const title = await page.title(); return title;'

# Or pipe code from stdin

cat <<'TS' | kernel browsers playwright execute my-browser

await page.goto("https://example.com");

const title = await page.title();

return { title };

TS

# With a timeout in seconds

kernel browsers playwright execute my-browser --timeout 30 'await (await context.newPage()).goto("https://example.com")'

# Mini CDP connection load test (10s)

cat <<'TS' | kernel browsers playwright execute my-browser

const start = Date.now();

let ops = 0;

while (Date.now() - start < 10_000) {

  await page.evaluate("new Date();");

  ops++;

}

const durationMs = Date.now() - start;

const opsPerSec = ops / (durationMs / 1000);

return { opsPerSec, ops, durationMs };

TS

```

### Extension management

```bash

# List all uploaded extensions

kernel extensions list

# Upload an unpacked extension directory

kernel extensions upload ./my-extension --name my-custom-extension

# Download an extension from Chrome Web Store

kernel extensions download-web-store "https://chrome.google.com/webstore/detail/extension-id" --to ./downloaded-extension

# Download a previously uploaded extension

kernel extensions download my-extension-id --to ./my-extension

# Delete an extension

kernel extensions delete my-extension-name --yes

# Upload extensions to a running browser instance

kernel browsers extensions upload my-browser ./extension1 ./extension2

```

### Proxy management

```bash

# List proxy configurations

kernel proxies list

# Create a datacenter proxy

kernel proxies create --type datacenter --country US --name "US Datacenter"

# Create a datacenter proxy using HTTP protocol

kernel proxies create --type datacenter --country US --protocol http --name "US DC (HTTP)"

# Create a custom proxy

kernel proxies create --type custom --host proxy.example.com --port 8080 --username myuser --password mypass --name "My Custom Proxy"

# Create a residential proxy with location and OS

kernel proxies create --type residential --country US --city sanfrancisco --state CA --zip 94107 --asn AS15169 --os windows --name "SF Residential"

# Create a mobile proxy with carrier

kernel proxies create --type mobile --country US --carrier verizon --name "US Mobile"

# Get proxy details

kernel proxies get prx_123

# Delete a proxy (skip confirmation)

kernel proxies delete prx_123 --yes

```

## Getting Help

- `kernel --help` - Show all available commands

- `kernel  --help` - Get help for a specific command

## Documentation

For complete documentation, visit:

- [📖 Documentation](https://onkernel.com/docs)

- [🚀 Quickstart Guide](https://onkernel.com/docs/quickstart)

- [📋 CLI Reference](https://onkernel.com/docs/reference/cli)

## Support

- [Discord Community](https://discord.gg/kernel)

- [GitHub Issues](https://github.com/onkernel/kernel/issues)

- [Documentation](https://onkernel.com/docs)

---

For development and contribution information, see [DEVELOPMENT.md](./DEVELOPMENT.md).