charm run - Charm Docs

Run a Charm agent locally. Use charm run while developing agent logic, testing input schemas, and checking runtime compatibility before publishing.

Usage

charm run [path] [--input <text>] [--json <payload>] [--input-file <file>] [--docker]

charm run . --input "Write a short welcome message"

Use JSON when your interface.input defines multiple fields:

charm run . --json '{"message": "Hello", "tone": "friendly"}'

Use --input-file for repeatable test cases:

charm run . --input-file test-cases.json

Example test file:

[
  {
    "name": "Basic greeting",
    "input": {
      "message": "Hello"
    }
  }
]

Run inside a container to better match the cloud runtime:

charm run . --input "Hello" --docker

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

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

charm run . --json '{"message": "Check my calendar"}' --mock-oauth
charm run . --json '{"message": "Use a skill"}' --mock-skills

Add --debug for extra logs:

charm run . --input "Hello" --debug