> ## 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. # CLI Reference 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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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. ### `charm auth login` 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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} charm auth manual --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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} charm validate ``` **Checks Performed:** 1. **Schema Validation:** Ensures `charm.yaml` strictly conforms to the UAC specification. 2. **Path Portability:** Scans internal Python files for hardcoded absolute paths (e.g., `/Users/dev/...`) which will instantly crash when deployed to the cloud runner. 3. **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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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.