CLI Reference - Charm Docs

The Charm CLI (charmos) is the definitive tool to scaffold, test, validate, and deploy intelligent agents to the Charm ecosystem. Built with a focus on developer experience, it brings the entire Charm Cloud Runner capability down to your local machine.

Installation

Install or upgrade the CLI globally via pip. We recommend using Python 3.10 or newer.

pip install -U charmos

[!TIP] Zero-Latency Update Checker The CLI automatically checks PyPI for updates in the background. If a new version is available, it will display a seamless non-blocking notification in your terminal.

Global Options

Every command in the Charm CLI supports standard global modifiers for debugging and system info.

Option	Shorthand	Description
`--help`		Display detailed, interactive documentation and parameter lists for any command (e.g., `charm run --help`).
`--debug`		Elevates the internal logging context. Prints raw HTTP server payloads, intercepts internal exceptions to print full stack traces, and provides verbose outputs. Crucial for debugging `Connection Error` or deployment failures.
`--version`	`-v`	Prints the currently installed version of `charmos` and exits.

Authentication (`charm auth`)

Manages your connection to the Charm Developer portal. You must be authenticated to push agents to the platform or read secure execution logs. Opens a secure local OAuth server and redirects your browser to authenticate your CLI session with your Charm account.

`charm auth whoami`

Prints the email address and token status of the currently authenticated developer.

`charm auth manual`

If you are operating in a headless environment (e.g., SSH, CI/CD pipeline) where a browser cannot be opened, use this command to paste a Personal Access Token directly.

charm auth manual --token <YOUR_TOKEN>

`charm auth logout`

Purges the local credential configuration (~/.charm/config.toml).

Project Initialization (`charm init`)

Scaffolds a new Charm Agent project. It auto-generates the required charm.yaml manifest and injects the necessary boilerplate code based on the chosen runtime adapter.

# Initialize interactive wizard
charm init --interactive

# Initialize a new code-based agent instantly
charm init my-new-agent --template python

Option	Default	Description
`[name]`	`.`	The directory path to scaffold the project into. Use `.` for the current directory.
`--template`	`python`	The starting template. Valid options: `python`, `openclaw`, `research-agent`, `code-review-agent`, `customer-support-agent`, `data-pipeline-agent`, `slack-bot`.
`--create`		Generate only a single file from a template instead of scaffolding a full folder (e.g. `--create charm.yaml`).
`--interactive`	`false`	Launch the interactive TUI prompt to visually guide you through project setup.

Local Development (`charm run`)

The most powerful command in your local workflow. charm run allows you to execute your agent locally using identical boundaries to the Cloud Runner simulator.

# Run in interactive CLI chat mode
charm run

# Run a headless JSON payload test
charm run --json '{"query": "Summarize the latest AI trends"}'

# Simulate the exact cloud container environment locally
charm run --docker --mock-oauth

Option	Shorthand	Description
`[path]`	`.`	Path to the Charm project root.
`--input`	`-i`	Send a simple string text input to the agent.
`--json`		Send a complex, deeply-nested raw JSON payload.
`--input-file`	`-f`	Provide a path to a JSON file containing a list of structured test cases to bulk-run logic tests.
`--docker`		Advanced: Boots a real-time local Docker container strictly mimicking the production `ucmind/runner-base` environment, mounting your code, and outputting server-sent events (SSE).
`--mock-oauth`		Injects dummy OAuth tokens (`GOOGLE_OAUTH_TOKEN`, etc.) into your environment.
`--mock-skills`		Forces the executor to bypass actual MCP skill connections for isolated unit testing.

Validation (`charm validate`)

Performs a rigorous local static analysis of your project. This command executes prior to charm push but can be run manually to lint your setup.

charm validate

Checks Performed:

Schema Validation: Ensures charm.yaml strictly conforms to the UAC specification.
Path Portability: Scans internal Python files for hardcoded absolute paths (e.g., /Users/dev/...) which will instantly crash when deployed to the cloud runner.
Entry Point Verification: For Python and Custom adapters, it imports your main.py locally and maps the signature to ensure your agent(inputs, callbacks) conforms exactly to the required parameters.

Deployment (`charm push`)

Bundles your source code, computes the .charmignore exclusions, and securely deploys your agent globally onto the Charm Store. When your deployment is completed, the CLI will trigger an auto-restart for existing installations and automatically copy your dedicated Store Distribution URL directly into your operating system’s clipboard.

charm push

Option	Description
`[path]`	Path to the Charm project root (defaults to `.`).
`--dry-run`	Executes the entire build process to display exactly which files will be packaged and the resulting bundle size in Megabytes, but halts before uploading.

[!WARNING] Charm enforces a strict maximum bundle size of 50.0 MB. If you are bundling heavy machine-learning checkpoint files or non-essential directories (like node_modules or .venv), use .charmignore to exclude them.

Telemetry (`charm logs`)

Securely tails the cloud execution logs of your specific agent without forcing context-switches to the web-based Studio dashboard.

charm logs

Option	Shorthand	Description
`--limit`	`-l`	The number of recent historical log events to fetch (max 500). Default is 50.

[!NOTE] Authentication Check The charm logs command requires the invoking machine to possess a valid authentication token belonging to the creator or an authorized owner of the agent. Unauthorized requests will result in a 403 Access Denied response.

​Installation

​Global Options

​Authentication (charm auth)

​charm auth login

​charm auth whoami

​charm auth manual

​charm auth logout

​Project Initialization (charm init)

​Local Development (charm run)

​Validation (charm validate)

​Deployment (charm push)

​Telemetry (charm logs)