### Install Earl CLI (Windows)

Source: https://brwse.github.io/earl/docs/quick-start

Installs the Earl command-line interface on Windows using PowerShell. This command downloads and executes an installation script.

```powershell
irm https://raw.githubusercontent.com/brwse/earl/main/scripts/install.ps1 | iex
```

--------------------------------

### Install setup-earl Skill using cURL

Source: https://brwse.github.io/earl/docs/agent-assisted-setup

Installs the `setup-earl` skill by creating the necessary directory and downloading the skill's markdown file from a GitHub URL using `curl`. This is the first step to enable agent-assisted setup in Claude Code.

```bash
mkdir -p ~/".claude/skills/setup-earl"
curl -fsSL https://raw.githubusercontent.com/brwse/earl/main/skills/development/setup-earl/SKILL.md \
  -o ~/".claude/skills/setup-earl/SKILL.md"
```

--------------------------------

### Install setup-earl Skill Inline

Source: https://brwse.github.io/earl/docs/agent-assisted-setup

An alternative method to install the `setup-earl` skill by fetching its content and any referenced files directly from GitHub. This approach bypasses the manual file creation and is useful for immediate use or environments where direct file manipulation is restricted.

```bash
Fetch https://raw.githubusercontent.com/brwse/earl/main/skills/development/setup-earl/SKILL.md
and any files it references under
https://raw.githubusercontent.com/brwse/earl/main/skills/development/references/
then follow the skill to set up Earl for this project.
```

--------------------------------

### List Available Earl Templates

Source: https://brwse.github.io/earl/docs/quick-start

Lists all pre-built provider templates available for import into Earl. This command helps users discover available integrations.

```bash
earl templates list
```

--------------------------------

### Verify Earl Installation

Source: https://brwse.github.io/earl/docs/quick-start

Runs the 'earl doctor' command to check the Earl installation and report any potential issues. This is a crucial step after installation to ensure Earl is set up correctly.

```bash
earl doctor
```

--------------------------------

### Install Earl CLI (macOS/Linux)

Source: https://brwse.github.io/earl/docs/quick-start

Installs the Earl command-line interface on macOS and Linux using a curl script. This method does not require a pre-installed Rust toolchain.

```bash
curl -fsSL https://raw.githubusercontent.com/brwse/earl/main/scripts/install.sh | bash
```

--------------------------------

### Import GitHub Provider Template

Source: https://brwse.github.io/earl/docs/quick-start

Imports the pre-built GitHub provider template into Earl. This allows Earl to interact with GitHub APIs. The template is specified by its URL.

```bash
earl templates import https://raw.githubusercontent.com/brwse/earl/main/examples/github.hcl
```

--------------------------------

### Start Earl HTTP Server

Source: https://brwse.github.io/earl/docs/policy-engine

These commands demonstrate how to start the Earl HTTP server. The first command starts the server on a specific address and port. The second command shows how to start the server locally with authentication disabled for development purposes.

```bash
earl mcp http --listen 0.0.0.0:8977

```

```bash
earl mcp http --listen 127.0.0.1:8977 --allow-unauthenticated

```

--------------------------------

### Run Earl Command with JSON Output

Source: https://brwse.github.io/earl/docs/quick-start

Executes an Earl command to call the GitHub 'search_repos' template. It uses the '--yes' flag to pre-approve the call and '--json' to get structured output. Both flags must precede the command name.

```bash
earl call --yes --json github.search_repos --query "language:rust stars:>100"
```

--------------------------------

### Install Earl CLI (macOS/Linux via Cargo)

Source: https://brwse.github.io/earl/docs/quick-start

Installs the Earl command-line interface on macOS and Linux using Cargo, the Rust package manager. This method requires the Rust toolchain, Node.js, and pnpm to be installed.

```rust
cargo install earl
```

--------------------------------

### Earl Command Execution Example

Source: https://brwse.github.io/earl/docs/browser

Demonstrates how to execute the 'snapshot_page' command defined in Earl. This example shows the command-line syntax for calling the command and passing the required URL parameter.

```bash
earl call web.snapshot_page --url https://example.com
```

--------------------------------

### Execute Earl Command via Bash Tool

Source: https://brwse.github.io/earl/docs/agent-assisted-setup

Demonstrates how to call Earl commands using the `earl call` command through a Bash tool. This method is available in the current session after Earl is installed but before the agent is restarted, allowing immediate interaction with Earl's functionalities.

```bash
earl call --yes --json provider.command --param value
```

--------------------------------

### Starting the HTTP Server

Source: https://brwse.github.io/earl/docs/policy-engine

Commands to start the Earl MCP HTTP server, with options for secure authentication or allowing unauthenticated access for local development.

```APIDOC
## Starting the HTTP Server

```bash
earl mcp http --listen 0.0.0.0:8977
```

Earl won't start without either `[auth.jwt]` configured or `--allow-unauthenticated` passed. You can't use both.

For local dev:

```bash
earl mcp http --listen 127.0.0.1:8977 --allow-unauthenticated
```

`--allow-unauthenticated` skips authentication and the policy engine. Don't use it anywhere shared.
```

--------------------------------

### Discovery Mode Tool Search and Call Examples

Source: https://brwse.github.io/earl/docs/mcp

These examples illustrate how an agent interacts with Earl in discovery mode. First, `earl.tool_search` is used with a natural language query to find relevant templates. Then, `earl.tool_call` is used with the identified tool name and its parameters to execute the action.

```python
earl.tool_search("find open pull requests on GitHub")
```

```python
earl.tool_call("github.list_pull_requests", { "owner": "myorg", "repo": "myrepo", "state": "open" })
```

--------------------------------

### SQL INSERT Example in Earl

Source: https://brwse.github.io/earl/docs/sql

Illustrates how to perform a write operation, specifically inserting a new user record, using the SQL protocol in an Earl template. It defines parameters for user name and email, specifies the connection secret, and configures the query with a `RETURNING` clause to get the new user's ID. Unlike read operations, write commands do not typically use a sandbox block for read-only restrictions.

```hcl
command "create_user" {
  title       = "Create user"
  summary     = "Insert a new user record"
  description = "Creates a user with the given name and email. Returns the new user's ID."

  annotations {
    mode    = "write"
    secrets = ["myapp.db_url"]
  }

  param "name" {
    type        = "string"
    required    = true
    description = "Full name"
  }

  param "email" {
    type        = "string"
    required    = true
    description = "Email address"
  }

  operation {
    protocol = "sql"

    sql {
      connection_secret = "myapp.db_url"
      query             = "INSERT INTO users (name, email, status) VALUES ($1, $2, 'active') RETURNING id"
      params            = ["{{ args.name }}", "{{ args.email }}"]
    }
  }

  result {
    decode = "json"
    output = "Created user {{ result[0].id }}"
  }
}
```

--------------------------------

### Use setup-earl Skill

Source: https://brwse.github.io/earl/docs/agent-skills

Instructs the agent to use the 'setup-earl' skill for installing and configuring Earl for a specific project, including setting up necessary configurations and context breadcrumbs.

```shell
Use the setup-earl skill to install and configure Earl for this project.
```

--------------------------------

### HTTP Streaming Example

Source: https://brwse.github.io/earl/docs/streaming

Demonstrates how to enable and configure HTTP streaming in Earl for a POST request.

```APIDOC
## POST /api/stream

### Description
This endpoint demonstrates how to enable and configure HTTP streaming for a POST request. Earl reads the response body line by line instead of buffering it, and the output template runs once per chunk, printing immediately.

### Method
POST

### Endpoint
https://api.example.com/stream

### Parameters
#### Query Parameters
None

#### Request Body
- **prompt** (string) - Required - The prompt to send to the API.

### Request Example
```json
{
  "prompt": "Your prompt here"
}
```

### Response
#### Success Response (200)
- **stream** (boolean) - Indicates if streaming is enabled.
- **output** (string) - The streamed output from the server.

#### Response Example
```json
{
  "stream": true,
  "output": "Partial response chunk 1"
}
```
```

--------------------------------

### gRPC Unary RPC Example

Source: https://brwse.github.io/earl/docs/grpc

This example demonstrates how to call a gRPC unary RPC endpoint to fetch a single inventory item by its ID.

```APIDOC
## POST /inventory.v1.ItemService/GetItem

### Description
Fetches a single inventory item by its ID, returning the item's name, quantity, and warehouse location.

### Method
gRPC (Unary)

### Endpoint
https://grpc.inventory.example.com

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (string) - Required - The unique identifier for the inventory item.

### Request Example
```json
{
  "id": "{{ args.id }}"
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the inventory item.
- **quantity** (integer) - The available quantity of the item.
- **warehouseLocation** (string) - The location of the item in the warehouse.

#### Response Example
```json
{
  "name": "Example Item",
  "quantity": 100,
  "warehouseLocation": "A1-3B"
}
```
```

--------------------------------

### Full Production Earl Configuration Example

Source: https://brwse.github.io/earl/docs/configuration

This TOML configuration provides a comprehensive setup for Earl in a production environment. It includes network access restrictions, JWT authentication for HTTP transport, OAuth2 profile for GitHub authentication, sandbox limits, default environment settings, access policy rules, and remote semantic search configuration.

```toml
# Network egress: allow only specific hosts
[[network.allow]]
scheme      = "https"
host        = "api.github.com"
port        = 443
path_prefix = "/"

[[network.allow]]
scheme      = "https"
host        = "api.stripe.com"
port        = 443
path_prefix = "/"

# JWT validation for MCP HTTP transport
[auth.jwt]
audience           = "https://api.yourcompany.com"
oidc_discovery_url = "https://accounts.yourcompany.com/.well-known/openid-configuration"

# OAuth2 profile for GitHub browser-based auth
[auth.profiles.github]
flow         = "auth_code_pkce"
client_id    = "your-client-id"
issuer       = "https://github.com"
scopes       = ["repo", "read:org"]
redirect_url = "http://localhost:8080/callback"

# Sandbox: tighter limits than the per-command defaults
[sandbox]
bash_allow_network    = false
bash_max_time_ms      = 10000
bash_max_output_bytes = 524288
sql_force_read_only   = true
sql_max_rows          = 50

# Default environment
[environments]
default = "production"

# Policy rules for MCP HTTP (only evaluated when auth.jwt is configured)
[[policy]]
subjects = ["user:*"]
tools    = ["github.*"]
modes    = ["read"]
effect   = "allow"

[[policy]]
subjects = ["*"]
tools    = ["github.delete_repo"]
modes    = ["write"]
effect   = "deny"

# Search: remote semantic search backend (optional)
[search.remote]
enabled          = true
base_url         = "https://search.yourcompany.com"
api_key_secret   = "search.api_key"
embeddings_path  = "/embeddings"
rerank_path      = "/rerank"
openai_compatible = true
timeout_ms       = 10000
```

--------------------------------

### Agent Description for GitHub Search

Source: https://brwse.github.io/earl/docs/best-practices

Provides an example of a useful agent description for the GitHub search command. It focuses on informing the agent about when to use the command and what qualifiers are effective, rather than just describing the mechanism.

```earl
# Less useful — describes the mechanism
description = "Calls the GitHub search API with a query string."

# More useful — tells the agent when to use it and what qualifiers work
description = <<-EOT
  Search GitHub repositories by topic, language, stars, or other qualifiers.
  Use qualifiers like 'language:rust', 'stars:>100', 'topic:cli'.
  Returns repo names, descriptions, and star counts.
EOT
```

--------------------------------

### Install Runtime 'earl' Skill

Source: https://brwse.github.io/earl/docs/agent-skills

Installs the 'earl' runtime skill, which is automatically invoked by the agent to discover and correctly call available Earl commands, including API calls, database queries, and shell commands.

```shell
mkdir -p ~/.claude/skills/earl
curl -fsSL https://raw.githubusercontent.com/brwse/earl/main/skills/runtime/earl/SKILL.md \
  -o ~/.claude/skills/earl/SKILL.md
```

--------------------------------

### Diagnostics

Source: https://brwse.github.io/earl/docs/commands

Command for diagnosing configuration and setup problems.

```APIDOC
## Diagnostics (`earl doctor`)

**Description**: Diagnoses configuration and setup problems.

**Method**: `earl doctor`

**Endpoint**: N/A (CLI command)

**Parameters**:

#### Path Parameters
None

#### Query Parameters
- `--json` (boolean) - Optional - Outputs results in machine-readable JSON format.

#### Request Body
None

**Usage Examples**:
```bash
earl doctor
earl doctor --json
```

**Checks Performed**:
- Config file: can it be found and parsed?
- Network allowlist: how many rules are configured?
- Template files: are any found in `./templates/` or `~/.config/earl/templates/`?
- Template validation: do all templates pass schema validation?
- Commands: does the catalog load and have at least one command?
- Required secrets: are all secrets declared in template annotations present in the keychain?
- OAuth profiles: do templates reference profiles that are configured?
- Remote search: if enabled, is it configured correctly?
- JWT config: is `[auth.jwt]` set up correctly?
- Policy rules: are `[[policy]]` entries well-formed?
- Bash sandbox tool: is the sandbox executable available?

**Output**: Each check reports `ok`, `warning`, or `error`. Doctor exits non-zero if any check is an error.
```

--------------------------------

### Configure Claude Code MCP Server

Source: https://brwse.github.io/earl/docs/quick-start

Adds Earl as an MCP (Message Communication Protocol) server to the Claude Code settings. This allows Claude to use Earl templates as native tools after restarting the agent.

```json
{
  "mcpServers": {
    "earl": {
      "command": "earl",
      "args": ["mcp", "stdio"]
    }
  }
}
```

--------------------------------

### Start Earl MCP stdio with Auto-Confirmation

Source: https://brwse.github.io/earl/docs/mcp

This command starts Earl's MCP server over stdio with the `--yes` flag. This flag pre-approves all write-mode commands for the session, preventing hangs in agents that do not surface MCP log messages. Use with caution as it bypasses individual confirmation prompts.

```bash
earl mcp stdio --yes
```

--------------------------------

### gRPC with Descriptor File

Source: https://brwse.github.io/earl/docs/grpc

This example shows how to configure a gRPC call when the server does not support reflection, by providing a compiled descriptor set file.

```APIDOC
## POST /inventory.v1.ItemService/GetItem (with descriptor file)

### Description
Fetches a single inventory item by its ID using a pre-compiled descriptor file for schema discovery. This is useful when the gRPC server does not support reflection.

### Method
gRPC (Unary)

### Endpoint
https://grpc.inventory.example.com

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (string) - Required - The unique identifier for the inventory item.

### Request Example
```json
{
  "id": "{{ args.id }}"
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the inventory item.
- **quantity** (integer) - The available quantity of the item.
- **warehouseLocation** (string) - The location of the item in the warehouse.

#### Response Example
```json
{
  "name": "Example Item",
  "quantity": 100,
  "warehouseLocation": "A1-3B"
}
```

### Notes
- The `descriptor_set_file` path is relative to the template file.
- Generate the descriptor file using `protoc --descriptor_set_out=inventory.pb --include_imports inventory.proto`.
```

--------------------------------

### Initiate Earl Authentication Flow

Source: https://brwse.github.io/earl/docs/agent-assisted-setup

Provides the command to initiate an OAuth PKCE authentication flow for Earl. This command is executed by the user when the agent cannot complete the browser redirect, allowing the user to finish the authentication process manually.

```bash
earl auth login <profile>
```

--------------------------------

### Install Earl Agent Skill

Source: https://brwse.github.io/earl/docs/agent-skills

Installs a skill for Claude Code or other agent platforms by downloading the SKILL.md file to the appropriate directory. It requires specifying the category and skill name.

```shell
mkdir -p ~/.claude/skills/<skill-name>
curl -fsSL https://raw.githubusercontent.com/brwse/earl/main/skills/<category>/<skill-name>/SKILL.md \
  -o ~/.claude/skills/<skill-name>/SKILL.md
```

--------------------------------

### Start GNOME Keyring Daemon (Linux)

Source: https://brwse.github.io/earl/docs/troubleshooting

On Linux systems using GNOME, this command checks if the `gnome-keyring-daemon` is running and starts it if necessary. This is crucial for `earl secrets set` to function correctly.

```shell
# Check if the daemon is running
ps aux | grep gnome-keyring

# Start it manually if not
eval $(gnome-keyring-daemon --start --components=secrets)
export DBUS_SESSION_BUS_ADDRESS
```

--------------------------------

### Use create-template Skill for API

Source: https://brwse.github.io/earl/docs/agent-skills

Guides the agent to create a new Earl template for a specified API. This involves identifying endpoints, determining authentication methods, writing HCL, testing, and storing secrets.

```shell
Use the create-template skill to build an Earl template for the Linear API.
```

--------------------------------

### Configure Network Egress Allowlist in Earl (TOML)

Source: https://brwse.github.io/earl/docs/hardening

Restricts which public hosts Earl can contact. Requests to hosts not on the list are rejected. Each entry requires scheme, host, port, and path_prefix. Wildcard support is not available for hosts.

```toml
[[network.allow]]
scheme      = "https"
host        = "api.github.com"
port        = 443
path_prefix = "/"

[[network.allow]]
scheme      = "https"
host        = "api.stripe.com"
port        = 443
path_prefix = "/"

```

--------------------------------

### Configure SQL Read-Only Sandbox

Source: https://brwse.github.io/earl/docs/hardening

Configure security settings for SQL queries within a sandbox. This enables read-only mode to prevent write operations and sets a maximum number of rows to be returned, safeguarding against excessive data retrieval. Parameters are passed securely to prevent SQL injection.

```hcl
sql {
  connection_secret = "myapp.db_url"
  query             = "SELECT id, name FROM users WHERE status = $1 LIMIT $2"
  params            = ["{{ args.status }}", "{{ args.limit }}"]
  sandbox {
    read_only = true
    max_rows  = 100
  }
}
```

--------------------------------

### Setting up 1Password CLI for Earl

Source: https://brwse.github.io/earl/docs/external-secrets

Instructions for installing and authenticating the 1Password CLI, which Earl uses to access secrets via `op://` URIs. No additional configuration in Earl's `config.toml` is required as it directly interfaces with the authenticated `op` CLI session.

```shell
# Install from https://developer.1password.com/docs/cli/
brew install 1password-cli

# Sign in
op signin
```

--------------------------------

### List Stored Secrets

Source: https://brwse.github.io/earl/docs/quick-start

Lists the metadata of secrets that have been stored using 'earl secrets set'. This command confirms that secrets are stored but does not reveal their values.

```bash
earl secrets list
```

--------------------------------

### Store Secret in OS Keychain

Source: https://brwse.github.io/earl/docs/quick-start

Sets a secret, such as an API token, using the 'earl secrets set' command. The secret is stored securely in the operating system's keychain and is not exposed in logs or LLM context.

```bash
earl secrets set github.token
```

--------------------------------

### Run GitHub Repository Search Command in Staging

Source: https://brwse.github.io/earl/docs/environments

This bash command demonstrates how to execute the 'search_repos' command defined in the Earl configuration against the 'staging' environment. It specifies the environment and provides a query parameter to search for Rust repositories.

```bash
earl call --env staging github.search_repos --query "language:rust"
```

--------------------------------

### Configure Basic Authentication

Source: https://brwse.github.io/earl/docs/template-schema

Sets up Basic authentication using a username and a password retrieved from the OS keychain. The username can be a static string or a Jinja expression, including secrets.

```hcl
auth {
  kind            = "basic"
  username        = "{{ secrets.jira_email }}"
  password_secret = "provider.password"
}
```

--------------------------------

### Verify Earl Installation (macOS/Linux)

Source: https://brwse.github.io/earl/docs/troubleshooting

Check if the Earl binary is installed and accessible in your system's PATH. This is a prerequisite for running `earl doctor` and other Earl commands.

```shell
which earl
earl --version
```

--------------------------------

### List and Search Available Earl Templates

Source: https://brwse.github.io/earl/docs/mcp

These commands show how to list all available Earl templates or search for specific templates using keywords. This is helpful for understanding the available tooling before integrating with an agent.

```bash
earl templates list
```

```bash
earl templates search "what you want to do"
```

--------------------------------

### Search Repositories

Source: https://brwse.github.io/earl/docs/environments

This endpoint allows you to search for GitHub repositories based on a given query. You can specify the number of results per page.

```APIDOC
## GET /search/repositories

### Description
Search GitHub repositories using GitHub's search API.

### Method
GET

### Endpoint
https://api.github.com/search/repositories

### Parameters
#### Query Parameters
- **query** (string) - Required - Search query (e.g. 'language:rust stars:>100')
- **per_page** (integer) - Optional - Results per page (max 100), defaults to 20

### Request Example
```json
{
  "query": "language:rust",
  "per_page": 50
}
```

### Response
#### Success Response (200)
- **total_count** (integer) - The total number of repositories found.
- **items** (array) - An array of repository objects.
  - **full_name** (string) - The full name of the repository.

#### Response Example
```json
{
  "total_count": 12345,
  "items": [
    {
      "full_name": "rust-lang/rust"
    },
    {
      "full_name": "tokio-rs/tokio"
    }
  ]
}
```
```

--------------------------------

### Get Secret Metadata

Source: https://brwse.github.io/earl/docs/commands

Retrieves metadata for a stored secret using the 'earl secrets get' command. Displays the key name, creation time, and last-updated time. The secret value is always redacted and cannot be displayed.

```bash
earl secrets get github.token
```

--------------------------------

### Start Earl MCP HTTP Transport

Source: https://brwse.github.io/earl/docs/mcp

This command starts Earl as an MCP server using the HTTP transport, making it accessible over a network. It specifies the listen address and port. Authentication can be configured via JWT or by allowing unauthenticated requests on trusted networks.

```bash
earl mcp http --listen 0.0.0.0:8977
```

--------------------------------

### Call GitHub Search Repos Command

Source: https://brwse.github.io/earl/docs/best-practices

Demonstrates how to call the `search_repos` command in Earl, specifying a query for repositories in Rust. This follows the recommended verb_noun snake_case naming convention for commands.

```earl
earl call github.search_repos --query "language:rust"
```

--------------------------------

### SQL Read Query Example in Earl

Source: https://brwse.github.io/earl/docs/sql

Demonstrates how to execute a read query against a database using the SQL protocol in an Earl template. It includes defining parameters for filtering and limiting results, specifying connection secrets, and processing the output. The sandbox block is used to enforce read-only access, row limits, and query timeouts.

```hcl
version = 1
provider = "myapp"
categories = ["database", "users"]

command "list_users" {
  title       = "List users"
  summary     = "List users filtered by status"
  description = "Returns user IDs and names for the given status. Defaults to active users."

  annotations {
    mode    = "read"
    secrets = ["myapp.db_url"]
  }

  param "status" {
    type        = "string"
    required    = false
    default     = "active"
    description = "User status filter (active, inactive, suspended)"
  }

  param "limit" {
    type        = "integer"
    required    = false
    default     = 50
    description = "Maximum rows to return"
  }

  operation {
    protocol = "sql"

    sql {
      connection_secret = "myapp.db_url"
      query             = "SELECT id, name, email FROM users WHERE status = $1 ORDER BY created_at DESC LIMIT $2"
      params            = ["{{ args.status }}", "{{ args.limit }}"]
      sandbox {
        read_only   = true
        max_rows    = 100
        max_time_ms = 5000
      }
    }
  }

  result {
    decode = "json"
    output = "{{ result | length }} users:\n{% for u in result %}  - {{ u.id }}: {{ u.name }} ({{ u.email }})\n{% endfor %}"
  }
}
```

--------------------------------

### Storage API

Source: https://brwse.github.io/earl/docs/template-schema

Manages local and session storage, including getting, setting, deleting, and clearing items.

```APIDOC
## Storage API

### Description
Provides access to browser's local and session storage.

### Endpoints

#### `local_storage_get`
*   **Description**: Retrieves an item from local storage.
*   **Method**: GET (assumed)
*   **Endpoint**: `/local_storage_get`
*   **Parameters**:
    *   **Query Parameters**:
        *   `key` (string) - Required - The key of the item to retrieve.
*   **Response**:
    *   **Success Response (200)**:
        *   `value` (string) - The value of the item.
    *   **Response Example**:
        ```json
        {
          "value": "stored_value"
        }
        ```

#### `local_storage_set`
*   **Description**: Sets an item in local storage.
*   **Method**: POST (assumed)
*   **Endpoint**: `/local_storage_set`
*   **Parameters**:
    *   **Request Body**:
        *   `key` (string) - Required - The key of the item.
        *   `value` (string) - Required - The value to set.
*   **Response**:
    *   **Success Response (200)**:
        *   `ok` (boolean) - Indicates if the item was set successfully.
    *   **Response Example**:
        ```json
        {
          "ok": true
        }
        ```

#### `local_storage_delete`
*   **Description**: Deletes an item from local storage.
*   **Method**: POST (assumed)
*   **Endpoint**: `/local_storage_delete`
*   **Parameters**:
    *   **Request Body**:
        *   `key` (string) - Required - The key of the item to delete.
*   **Response**:
    *   **Success Response (200)**:
        *   `ok` (boolean) - Indicates if the item was deleted successfully.

```

--------------------------------

### Cookie Management API

Source: https://brwse.github.io/earl/docs/template-schema

Provides endpoints for managing cookies, including listing, getting, setting, and deleting them.

```APIDOC
## Cookie Management API

### Description
Manages browser cookies for the current domain.

### Endpoints

#### `cookie_list`
*   **Description**: Lists all cookies for the current domain or a specified domain.
*   **Method**: GET (assumed)
*   **Endpoint**: `/cookie_list`
*   **Parameters**:
    *   **Query Parameters**:
        *   `domain` (string) - Optional - Filter cookies by domain.
*   **Response**:
    *   **Success Response (200)**:
        *   `cookies` (array of objects) - A list of cookie objects.
    *   **Response Example**:
        ```json
        {
          "cookies": [
            {
              "name": "cookie1",
              "value": "value1"
            }
          ]
        }
        ```

#### `cookie_get`
*   **Description**: Retrieves a specific cookie by name.
*   **Method**: GET (assumed)
*   **Endpoint**: `/cookie_get`
*   **Parameters**:
    *   **Query Parameters**:
        *   `name` (string) - Required - The name of the cookie to retrieve.
*   **Response**:
    *   **Success Response (200)**:
        *   `value` (string) - The value of the cookie.
    *   **Response Example**:
        ```json
        {
          "value": "cookie_value"
        }
        ```

#### `cookie_set`
*   **Description**: Sets a cookie.
*   **Method**: POST (assumed)
*   **Endpoint**: `/cookie_set`
*   **Parameters**:
    *   **Request Body**:
        *   `name` (string) - Required - The name of the cookie.
        *   `value` (string) - Required - The value of the cookie.
        *   `domain` (string) - Optional - The domain for the cookie.
        *   `path` (string) - Optional - The path for the cookie.
        *   `expires` (integer) - Optional - Expiration timestamp.
        *   `http_only` (boolean) - Optional - Whether the cookie is HTTP only.
        *   `secure` (boolean) - Optional - Whether the cookie is secure.
*   **Response**:
    *   **Success Response (200)**:
        *   `ok` (boolean) - Indicates if the cookie was set successfully.
    *   **Response Example**:
        ```json
        {
          "ok": true
        }
        ```

#### `cookie_delete`
*   **Description**: Deletes a cookie by name.
*   **Method**: POST (assumed)
*   **Endpoint**: `/cookie_delete`
*   **Parameters**:
    *   **Request Body**:
        *   `name` (string) - Required - The name of the cookie to delete.
*   **Response**:
    *   **Success Response (200)**:
        *   `ok` (boolean) - Indicates if the cookie was deleted successfully.
    *   **Response Example**:
        ```json
        {
          "ok": true
        }
        ```

#### `cookie_clear`
*   **Description**: Clears all cookies for the current domain.
*   **Method**: POST (assumed)
*   **Endpoint**: `/cookie_clear`
*   **Parameters**: None
*   **Response**:
    *   **Success Response (200)**:
        *   `ok` (boolean) - Indicates if all cookies were cleared successfully.
    *   **Response Example**:
        ```json
        {
          "ok": true
        }
        ```
```

--------------------------------

### Server-Sent Events (SSE) Streaming with OpenAI API

Source: https://brwse.github.io/earl/docs/streaming

Example of streaming a chat completion response token by token using SSE from the OpenAI API.

```APIDOC
## POST /v1/chat/completions (SSE)

### Description
This command streams a chat completion response token by token using Server-Sent Events (SSE). It calls the OpenAI completions API and prints tokens as they arrive. The `data: ` prefix is stripped before decoding, and non-JSON events like `[DONE]` are skipped automatically when `decode = "json"`.

### Method
POST

### Endpoint
https://api.openai.com/v1/chat/completions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The model to use for completion (e.g., "gpt-4o").
- **stream** (boolean) - Required - Set to `true` to enable streaming.
- **messages** (array) - Required - An array of message objects, each with `role` (string) and `content` (string).

### Request Example
```json
{
  "model": "gpt-4o",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Stream a chat completion response token by token"
    }
  ]
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array of choices, where each choice contains `delta` with `content` (string) representing a token.

#### Response Example
```json
{
  "choices": [
    {
      "delta": {
        "content": "Hello"
      }
    }
  ]
}
```

### Handling Non-JSON Events
If you need to handle all lines, including terminators like `[DONE]`, use `decode = "text"` in the result block and process the `result` in the template.

```
result {
  decode = "text"
  output = "{% if result != '[DONE]' %}{% set chunk = result | from_json %}{{ chunk.choices[0].delta.content | default('') }}{% endif %}"
}
```
```

--------------------------------

### Bash Sandbox Configuration

Source: https://brwse.github.io/earl/docs/how-earl-works

The Bash protocol allows running scripts within a sandbox environment. This sandbox can restrict network access, set a maximum execution time in milliseconds, and limit the maximum output size in bytes. These settings help mitigate risks associated with executing external scripts.

```hcl
bash {
  script = "echo 'Hello, World!'"
  sandbox {
    network          = false
    max_time_ms      = 30000
    max_output_bytes = 1048576
  }
}
```

--------------------------------

### Network Egress Allowlist Configuration

Source: https://brwse.github.io/earl/docs/how-earl-works

An optional network egress allowlist can be configured to restrict the external hosts Earl can contact. If an allowlist is defined, Earl will reject any request to a host not present in the list. This enhances security by limiting the potential impact of compromised templates or manipulated parameters.

```toml
[[network.allow]]
scheme      = "https"
host        = "api.github.com"
port        = 443
path_prefix = "/"
```

--------------------------------

### Secrets Management

Source: https://brwse.github.io/earl/docs/commands

Commands for managing secrets, including setting secrets from stdin, getting secret metadata, listing all secrets, and deleting secrets.

```APIDOC
## Secrets Management

### Set Secret from stdin

**Description**: Reads a secret value from standard input and stores it with a given key.

**Method**: `earl secrets set`

**Endpoint**: N/A (CLI command)

**Parameters**:

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

**Usage Examples**:
```bash
echo "ghp_xxxx" | earl secrets set github.token --stdin
cat token-file.txt | earl secrets set service.api_key --stdin
```

**Flags**:
- `--stdin`: Read the secret value from stdin instead of prompting.

**Notes**:
On macOS, the first write to the keychain may show a system dialog asking for permission. Click "Always Allow".

### Get Secret Metadata

**Description**: Shows metadata for a stored secret (key name, creation time, last-updated time). The value is always redacted.

**Method**: `earl secrets get`

**Endpoint**: N/A (CLI command)

**Parameters**:

#### Path Parameters
- `key` (string) - Required - The key of the secret to retrieve metadata for.

#### Query Parameters
None

#### Request Body
None

**Usage Example**:
```bash
earl secrets get github.token
```

**Output**: Includes key name, creation time, and last-updated time. The value field always shows `[REDACTED]`.

### List All Stored Secrets

**Description**: Lists all stored secret keys.

**Method**: `earl secrets list`

**Endpoint**: N/A (CLI command)

**Parameters**:
None

**Usage Example**:
```bash
earl secrets list
```

### Delete a Secret

**Description**: Removes a secret from the keychain.

**Method**: `earl secrets delete`

**Endpoint**: N/A (CLI command)

**Parameters**:

#### Path Parameters
- `key` (string) - Required - The key of the secret to delete.

#### Query Parameters
None

#### Request Body
None

**Usage Example**:
```bash
earl secrets delete github.token
```
```

--------------------------------

### GET /graphql - Fetch Repository Data

Source: https://brwse.github.io/earl/docs/graphql

This endpoint allows fetching basic information about a GitHub repository, such as its star count, description, and primary language.

```APIDOC
## POST /graphql

### Description
Fetches basic info about a GitHub repository, including star count, description, and primary language.

### Method
POST

### Endpoint
https://api.github.com/graphql

### Parameters
#### Query Parameters
- **owner** (string) - Required - Repository owner (user or org)
- **repo** (string) - Required - Repository name

#### Request Body
```json
{
  "query": "query($owner: String!, $repo: String!) {\n  repository(owner: $owner, name: $repo) {\n    stargazerCount\n    description\n    primaryLanguage { name }\n  }\n}\n",
  "variables": {
    "owner": "{{ args.owner }}",
    "repo": "{{ args.repo }}"
  }
}
```

### Request Example
```json
{
  "query": "query($owner: String!, $repo: String!) {\n  repository(owner: $owner, name: $repo) {\n    stargazerCount\n    description\n    primaryLanguage { name }\n  }\n}\n",
  "variables": {
    "owner": "torvalds",
    "repo": "linux"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the result of the GraphQL query.
  - **repository** (object) - Information about the repository.
    - **stargazerCount** (integer) - The number of stars the repository has.
    - **description** (string) - The description of the repository.
    - **primaryLanguage** (object) - The primary programming language used in the repository.
      - **name** (string) - The name of the primary language.

#### Response Example
```json
{
  "data": {
    "repository": {
      "stargazerCount": 150000,
      "description": "The Linux kernel source tree.",
      "primaryLanguage": {
        "name": "C"
      }
    }
  }
}
```
```

--------------------------------

### Set Global Sandbox Limits (TOML)

Source: https://brwse.github.io/earl/docs/configuration

Configures global defaults for Bash and SQL sandbox limits. These can be overridden by per-command blocks. Settings include network access, maximum execution time, output size, memory, CPU time, and SQL query restrictions.

```TOML
[sandbox]
bash_allow_network    = false
bash_max_time_ms      = 30000
bash_max_output_bytes = 1048576
bash_max_memory_bytes = 134217728
bash_max_cpu_time_ms  = 30000
sql_force_read_only   = true
sql_max_rows          = 100
sql_connection_allowlist = []

```

--------------------------------

### GET /user/repos

Source: https://brwse.github.io/earl/docs/http

Lists all repositories visible to the authenticated GitHub user, sorted by the last push. Supports pagination via the 'per_page' parameter.

```APIDOC
## GET /user/repos

### Description
Lists all repositories visible to the authenticated GitHub user, sorted by last push. Supports pagination.

### Method
GET

### Endpoint
https://api.github.com/user/repos

### Parameters
#### Query Parameters
- **per_page** (integer) - Optional - Results per page (max 100). Defaults to 30.

### Request Example
```json
{
  "per_page": 10
}
```

### Response
#### Success Response (200)
- **result** (array) - An array of repository objects, each containing details like `full_name`.

#### Response Example
```json
{
  "result": [
    {
      "id": 12345,
      "full_name": "user/repo1",
      "private": false
    },
    {
      "id": 67890,
      "full_name": "user/repo2",
      "private": true
    }
  ]
}
```

### Authentication
Requires a Bearer token, typically stored as a secret named `github.token`.
```

--------------------------------

### Parameterize URLs with path for Environment Variables

Source: https://brwse.github.io/earl/docs/best-practices

Use the `path` field in conjunction with `url` to manage environment-specific base URLs for operations. This allows the base URL to be defined in environment configurations, while the path remains visible within the command, simplifying environment switching and maintaining clear command logic.

```hcl
operation {
  protocol = "http"
  method   = "GET"
  url      = "{{ vars.base_url }}"
  path     = "/v2/users/{{ args.id }}"
}
```

--------------------------------

### Fetch and Follow Agent Skill Inline

Source: https://brwse.github.io/earl/docs/agent-skills

Allows an agent to fetch and execute a skill directly from a URL without writing it to disk. This is useful for temporary or on-the-fly skill usage.

```shell
Fetch https://raw.githubusercontent.com/brwse/earl/main/skills/<category>/<skill-name>/SKILL.md
and follow the skill to <goal>.
```

--------------------------------

### Configure Auth Code + PKCE OAuth2 Profile

Source: https://brwse.github.io/earl/docs/configuration

Sets up an OAuth2 profile using the Auth Code + PKCE flow. This flow requires human authorization via a browser and is suitable for interactive sessions. It uses a redirect URL for the authorization callback.

```toml
[auth.profiles.myprofile]
flow = "auth_code_pkce"
client_id = "your-client-id"
issuer = "https://accounts.example.com"
scopes = ["read", "write"]
redirect_url = "http://localhost:8080/callback"

```