# Baud > Use the baud CLI to diagnose and automate serial, UART, COM-port, USB-to-TTL, and firmware-console workflows. Trigger when Codex needs to enumerate serial ports, capture boot logs, diagnose silent or one-way communication, send device commands, run guarded YAML hardware tests, or interpret baud JSON, JSONL, logs, and exit codes. Prefer this skill over ad hoc pyserial scripts. - Skill: `nitmi/baud` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add nitmi/baud` - Raw SKILL.md: https://api.skillmd.com/api/skills/nitmi/baud/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Nitmi (https://skillmd.com/u/nitmi) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nitmi/baud --- # Baud Use `baud` as the serial execution layer. Preserve evidence, minimize transmission, and gate physical actions behind verified device state. ## Prepare 1. Run `baud --version` before opening a port. 2. If the command is unavailable, report the missing prerequisite. When installation is authorized, use `uv tool install baud-cli`; use `uv run --directory baud` only when the source checkout is known. Do not silently replace it with an ad hoc `pyserial` script. 3. Read applicable `AGENTS.md`, firmware documentation, and existing serial workflows to learn the baud rate, line ending, safe query commands, reset behavior, and physical risks. 4. Resolve the port from evidence. Do not assume a previous COM or tty name still identifies the same adapter. ## Choose The Least Invasive Command Follow this escalation order: 1. Run `baud list --json` to enumerate ports and USB metadata. 2. Run `baud monitor --port --duration --json` to observe boot output without transmitting. 3. Run `baud probe --port --commands --endings crlf lf --json` only after confirming the probe commands are harmless for the device. 4. Run `baud send` for one bounded query with explicit expectations. 5. Run `baud run --json` for multi-step configuration, observation, or hardware action. Use `--json` for a bounded command whose final result drives the next decision. Use `--jsonl` when event ordering or streamed evidence matters. Keep automatic log artifacts enabled for real hardware work. ## Apply Safety Gates - Start with read-only observation and status queries. - Treat DTR and RTS as physical control signals that may reset or reconfigure a device. Keep both false unless device documentation requires otherwise. - Confirm both communication directions before sending a state-changing command. A boot banner proves only device-to-host traffic. - Read configuration back from the device; do not treat ACK, echoed input, or a successful write as proof that hardware accepted the state. - Mark motion, heating, injection, erase, flash-save, power switching, and similar actions as `dangerous: true` in workflows. Require successful earlier verification steps with `requires`. - Begin physical testing with one cycle, the lowest safe setpoint, unloaded mechanics, or another documented low-risk condition. - Stop on a busy, disappearing, or unidentified port. Do not kill an unknown process or continue on a different port without evidence. Read [references/safety.md](references/safety.md) before transmitting to an unfamiliar device, controlling physical motion, changing DTR/RTS, or diagnosing resets and one-way communication. ## Run Guarded Workflows Prefer an existing repository workflow under locations such as `debug/serial/` or `examples/`. Inspect it before execution and verify that its commands match the connected firmware. When authoring a workflow: - Give every meaningful step a stable `id`. - Add positive read-back assertions and negative error assertions. - Keep waits local to the operation that needs them. - Make every dangerous step depend on all required verification steps. - Query final device state after asynchronous activity. - Preserve the generated `.log` and `.jsonl` paths in the result. Read [references/workflows.md](references/workflows.md) when creating or modifying YAML, selecting assertions, or interpreting workflow results and exit codes. ## Interpret Evidence Use the structured result before reading the human log: - Check `ok`, `exit_code`, `reason`, and `failed_step`. - Inspect the failed step's `text`, `bytes_received`, and assertion details. - Use JSONL timestamps and Base64 raw bytes when decoding, line endings, resets, or event order are disputed. - Distinguish `silent` from `device_tx_only_or_command_loop_not_running` and `responsive` probe diagnoses. - Treat a repeated startup banner after a command as evidence of a probable reset, not merely a missing response. Summarize the exact command, port identity, observed evidence, safety decision, and next diagnostic step. Do not claim hardware success from process exit alone when the workflow lacks a device-state assertion. ## Handle CLI Gaps Inspect `baud --help` before falling back. Use a temporary serial script only when `baud` cannot express a required diagnostic and the fallback is within the user's authorized hardware scope. Keep the fallback read-only first, preserve raw bytes, always close the port, and record the missing capability as a candidate `baud-cli` enhancement.