reachy-mini-cli

Start with what it is: a small desk robot that can look at you, listen for you, and move like it means it. reachy-mini-cli does not hide any of that behind an app — it hands you each capability as a plain command, so a human at a terminal and an agent in a loop reach the robot exactly the same way.

Here is the whole body, one line at a time. None of these is a promise for later; each is a noun that ships in 0.31.0.

This is the entire surface, nothing held back. Fourteen entries: thirteen robot nouns and one row of agent-first introspection that needs no robot at all. Every noun supports --json, and reachy-mini-cli explain <noun> prints its full flag reference.

Read the transport column closely — it is the whole operating model in one word per row. The sense nouns default to the in-process sdk transport; device, app, and move default to http, the daemon's REST API. That split is not an accident; it is the next section.

If you take one thing from this page, take this. The CLI will happily let you launch any two nouns at once, but the hardware underneath has two single resources, each with room for exactly one owner. This trips up humans and agents alike, over and over.

The first single resource is the SDK client and its media session: on the sdk transport, listen, think, and sleep each open a single-consumer mic session, and vision and pat read camera frames and head pose through the same one in-process client. So only one sdk-sense noun can own the robot at a time. The second is the head itself — every move, from an idle sway to a sound-orienting turn to an expression, flows through one serial motion queue, one move at a time, so motion is always smooth and never fights itself. Two motion drivers still fight over the same head.

Because both resources are single-owner, you cannot run two sdk-sense nouns as separate processes against one robot. The second one is starved — a stray pat process next to listen gets throttled to about one hertz, far too slow to feel a hand. There are exactly two ways to compose behaviors anyway, and the diagram beside this traces both.

Because only one sdk media owner can run at a time, the supported way to run all the senses at once is a single command — listen run --live — that folds think, vision, and sleep into listen's loop beside the head-pat hook. Every live sense rides the one media session and the one motion queue, in one process, arbitrated by those priority flags. This is exactly the loop the live boot presence runs.

Below is each behavior the folded loop carries. Where a sense is honest about its limits, the card says so — because the robot does too.

think is the noun where the body and the mind meet. Each turn snapshots what the robot just perceived — direction-of-arrival, mic loudness, speech — and asks an LLM for one or two short first-person sentences. The reply is sentence-streamed: the first sentence is synthesized and played while the later ones are still being generated, so thinking and speaking overlap the way they do in a person. Emoji markers in that stream drive calm body poses that arrive timed to the words, and each move goes onto the one serial motion queue. The captured demo runs three gestures against three spoken phrases so you can watch the timing without an LLM in the loop.

It has a second voice for when the first one is unreachable. The default is text-to-speech over an HTTP service, but that service can be down — and when it is, live cognition would otherwise go silent. So the robot also has a harmonic voice: fully offline, deterministic, in-process. It does not read the words; it renders their meaning as a short note-melody in the robot's own identity signature. Today's captures show both halves, separately and honestly: the default TTS run failed clean — an error line, a hint, no crash — and a second run that asked for the harmonic engine up front played its melody with no TTS service anywhere. The engine is chosen per run, with --voice-engine or REACHY_VOICE_ENGINE; when the speech service is down, the harmonic voice is the one you reach for.

And you can watch it think from outside. think run --export - streams a newline-delimited JSON feed of what the robot is thinking, saying, and feeling — one object per line, tagged thinking, message, or emotion, each with a timestamp. The renderer lives out of this repo by design: the CLI emits a documented contract, and a separate consumer renders it. Be precise about what ships, though — in 0.31.0 only the stdout sink, spelled '-', is wired. Point --export at a file or an HTTP URL and the CLI says so itself: only '-' (stdout) is supported in this version; HTTP and file sinks are future work. A clean exit-one error, not a broken promise.

One last honesty: the loop does nothing gracefully. When the sense-event buffer is empty, the turn is a no-op — no LLM call, no audio. A bounded think run against a quiet room can finish with zero spoken turns and that is the design, not a failure. It is the same discipline everywhere in this tool: the robot would rather do nothing legibly than fake being busy.

This is not a robot toy with a scripting hook bolted on. It is an agent-first CLI, cited from teken's agent-first foundation, and the same design that makes it pleasant for a person makes it drivable by a model. The introspection verbs — whoami, quickstart, learn, explain, overview, doctor — all work with no robot attached, so an agent can learn the whole surface before it touches hardware.

The contracts underneath are the point. Every command takes --json. Results go to stdout and diagnostics to stderr, never mixed, so a program can read the answer without parsing around chatter. Exit codes mean one thing each: zero for success, one for a user-input error, two for an environment error, three and up reserved. And a failure is never a Python traceback — it is a structured error: line with a hint: line telling you what to do next.

You can see the contract hold on a bare install. Run an sdk-transport noun without the SDK extra and you do not get an ImportError — you get exit two and a hint to install [sdk] or use --transport http. In today's captures the same shape appears for real: the TTS service was down, and the robot returned its clean error-and-hint pair rather than crashing; a second run asked for the offline harmonic voice explicitly and played through the same speaker. The failures on this page are the CLI keeping its promises.

The body is still growing, and its direction is checkable the same way its facts are: on the open tracker. Four currents stand out — and note that everything in this section is open work, not something 0.31.0 ships.