> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charmos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# charm run

Run a Charm agent locally.

Use `charm run` while developing agent logic, testing input schemas, and checking runtime compatibility before publishing.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run [path] [--input <text>] [--json <payload>] [--input-file <file>] [--docker]
```

## Simple Text Input

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Write a short welcome message"
```

## JSON Input

Use JSON when your `interface.input` defines multiple fields:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Hello", "tone": "friendly"}'
```

## Input File

Use `--input-file` for repeatable test cases:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input-file test-cases.json
```

Example test file:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
[
  {
    "name": "Basic greeting",
    "input": {
      "message": "Hello"
    }
  }
]
```

## Docker Sandbox

Run inside a container to better match the cloud runtime:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello" --docker
```

Docker mode requires `charmos[runner]` and a running Docker daemon.

## Mocked Integrations

For agents that require OAuth or skills, local mocks can speed up testing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --json '{"message": "Check my calendar"}' --mock-oauth
charm run . --json '{"message": "Use a skill"}' --mock-skills
```

## Debugging

Add `--debug` for extra logs:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
charm run . --input "Hello" --debug
```