OnMCU Client Documentation

Overview

onmcu is a CLI tool that implements relevant parts of the OnMCU controller server’s OpenAPI spec in Rust.

System Components

• onmcu: Command-line interface tool, written in Rust
• Webapp: Web interface for API key management, job history, and other information. Integrates with the OnMCU Controller and Identity Server.
• Controller: Proprietary server that provides endpoints for CLI and webapp, schedules jobs, and manages execution

Download

Download the latest onmcu binaries: Linux x86_64, Windows x86_64

Download the default config file here: client-doc.onmcu.com/config/config.toml

Getting Started

1. Obtain an API Key

1. Login to https://app.onmcu.com
2. Navigate to Settings
3. Add an API Key
4. Save the generated key - it cannot be shown again

2. Add API Key to CLI

Choose one of the following methods:

Option 1: Store in System Keyring (Recommended)

onmcu -c config.toml  login

Paste your API Key when prompted. It will be securely stored in your operating system’s keyring.

If you’re already logged in, this command will not prompt you for your API Key again. To update your API Key in that case, run onmcu -c config.toml login --relogin.

Option 2: Use Environment Variable

Intended for CI/CD systems. Set the ONMCU_API_KEY environment variable:

export ONMCU_API_KEY="your-api-key-here"
onmcu -c config.toml  run --api-key-from-env --board <board> --file <binary>

3. Run a Job

onmcu -c config.toml run --board <board-name> --file <path-to-binary>

Example:

onmcu -c config.toml run --board NUCLEO-H743ZI --file ./blinky

with config.toml specified like this:

chunk_size = 5
retries = 3
server = "https://ctrl1.onmcu.com"
timeout_seconds = 600

Parameters:

• --board: Board name (obtain via webapp or onmcu list-boards)
• --file: Path to raw binary compiled for the MCU on the selected board
• --api-key-from-env: Load API Key from ONMCU_API_KEY env variable vs keychain (for CI usage)
• --timeout: Timeout after which the job is automatically stoppped
• --verbose: Verbose logging for troubleshooting

Commands

List Available Boards

onmcu -c config.toml list-boards

Run Firmware

onmcu -c config.toml run --board <board-name> --file <path-to-binary>

Executes the firmware binary on the specified board and streams logs from probe-rs.