microduck-cli

One CLI for the MicroDuck robot — any agent, any human, the same verbs.

flowchart LR
  A["an agent<br/>(Claude, Codex, ...)"] --> C
  H["a human<br/>(a terminal)"] --> C
  C["<b>microduck-cli</b><br/>env · duck · policy · rules"]
  C -- "JSON-RPC over<br/>~/.cache/duck-sim/duck-a.sock" --> D["<b>robotd</b><br/>API 16"]
  D --> F["--fake body"]
  D --> S["MuJoCo body<br/>(microduck_rl duck-body)"]
  D -. "not driven yet" .-> R["a real MicroDuck"]

One unix socket, the daemon's own JSON-RPC, no robotics SDK — dependencies = [] is the whole runtime dependency list. Everything below was checked at microduck-cli 0.9.4 against its own --help, the real daemon, and the MuJoCo simulation on three machines.

Install

uv tool install microduck-cli     # or: uvx microduck-cli whoami
microduck --version

microduck and microduck-cli are the same entry point. From a checkout, prefix with uv run — the form docs/operating-the-duck.md uses:

git clone https://github.com/agentculture/microduck-cli && cd microduck-cli
uv sync && uv run microduck whoami

Python ≥ 3.12, Linux on aarch64 — the only platform on record (see Proof).

What it is

Five noun groups. Every verb takes --json; results go to stdout, diagnostics to stderr, never mixed. Exit 0 success, 1 your error, 2 the environment's.

What it is not

• It has never driven a real duck. Every verb is exercised against the MuJoCo simulation — the real robotd --sim daemon driving a duck that stands, holds 50 Hz and runs skills — plus a --fake body for the unit suite.
• It cannot walk yet. duck move reaches the daemon and selects the walk network, but the joint targets come back static. Details below.
• It cannot load policies on this daemon. robot.loadPolicy and friends need API ≥ 18; the pinned build answers API 16, and those verbs say so and exit 2.

If you do have a duck: motion is gated — no --apply, no movement — and duck relax drops torque, which makes the duck fall over.

Try it in simulation

Prerequisites. Two upstream clones at the pinned commits (docs/upstream-pins.md) and a Rust toolchain. Without them env doctor fails seven of its thirteen checks — that is the box, not the CLI. Point MICRODUCK_CLONE and DUCK_SIM_RL at the clones and ask:

microduck env doctor      # 13 checks: clone pins, cargo, daemons built, RL venv, port, state dir

Then, in order — this numbered walkthrough is the plain-text equivalent of the diagrams above and below, for readers whose renderer shows a mermaid fence as code:

1. Bring up a duck. --sim is the path the verification records below cover — the real daemon driving the MuJoCo body. Drop --headless to watch it in the viewer, or use --fake for a body that needs no simulator at all.

   microduck env up --sim --headless
   

2. Ask the robot for its own verdict.

   microduck duck health
   

3. Stand it up, then hand it its policy. Both are gated, hence --apply.

   microduck duck init --apply
   microduck duck enable --apply
   

4. Run the tick engine briefly. Connect, hello, health, init, enable, armed — each step logged, then 50 ticks at 50 Hz.

   microduck rules engine run --max-ticks 50 --apply
   

5. Inject one intent through the same admission registry a rule fires through.

   microduck rules intent stop
   

6. Tear it down. Never kill by name — env down is the supported path.

   microduck env down
   

docs/operating-the-duck.md walks the same six commands with each one's exact output and what to do when a check fails; the first-party operate-microduck skill is the same ground for an agent, including the screenshot recipe for watching the MuJoCo window from a headless session.

Proof — three boxes

Everything in this section is copied from the verification records in docs/verification/, not retyped. Home directories are shortened to ~; nothing else is changed. Each record names the box, the upstream pins, the daemon API and the CLI commit it was recorded at — and nothing re-runs them, so a re-pin ages them silently. Check the record's date against the pins table before trusting a number here.

A duck standing up in MuJoCo — Spark, CLI 420dc5c:

$ microduck env up --sim --headless --skip-build
waiting for duck-a to report healthy (~/.cache/duck-sim/duck-a.sock)...
microduck-cli env up: healthy (sim)
  duck-a: ~/.cache/duck-sim/duck-a.sock
$ microduck duck init --apply --json
{... "summary": "init accepted: ramping to the home pose", "result": {"accepted": true}}
$ microduck duck monitor --frames 2 --json     # 8 s later
{'policy': 'held', 'fallen': False, 'gravity': [-0.028, -0.00004, -0.9996], 'z': 0.0687, 'loop': {'hz': 50.03, 'missed': 0}}

The same trunk height, to four decimals, on a different box — Orin, CLI 3c09fb0 (0.9.1):

$ microduck duck health --json
{"healthy": true, "degraded": false, "health": {"control_loop": {"target_hz": 50.0,
 "achieved_hz": 49.999974411777806, "ticks": 900, "missed": 0, "last_tick_age_ms": 17}, ...}}

A rule firing, and a drop that says why — Spark, one overlay rule (fallen is false → look, cooldown 5 s) over a 300-tick run:

$ microduck rules engine run --duck duck-a --rules /tmp/duck-rules-test.toml --apply --max-ticks 300 --json
{'ticks': 300, 'achieved_hz': 50.0, 'overruns': 0}
[SENSE stage=rule source=verify-look event=fired] look -> look-1
[SENSE stage=rule source=verify-look event=cooldown] dropped reason=cooldown: fired 0.020s ago, cooldown_s is 5.0

229 cooldown drops over the run, every one named on the microduck.sense logger — stderr only, so JSONL on stdout stays pure. A layer whose drops are invisible is indistinguishable from one that silently does nothing.

The live suite against a real daemon — Thor, CLI 2b00480, MuJoCo body:

$ MICRODUCK_LIVE=1 MICRODUCK_LIVE_BODY=sim MICRODUCK_LIVE_SIM=1 ... uv run pytest -m live -n0 -v tests/live
(the eleven above) PASSED
test_sim_body_stands_the_duck_up PASSED
test_sim_body_walks_forward_on_move XFAIL
======================== 12 passed, 1 xfailed in 26.65s ========================

Those twelve drive the CLI as subprocesses against the real socket. The unit suite (1101 tests at 0.9.4; the records above were taken at 998) does not — it runs against the in-process Python fake.

Not verified

Stated plainly, because a record that only lists passes is a brochure:

• No physical duck. The --fake and MuJoCo bodies only.
• Walking. Sampled at 25 Hz during duck move --vx 0.15: policy: walk, move.applied [0.15, 0, 0], fallen: false — and the left-knee target moves between −0.09 and −0.05 rad over 97 frames while odometry goes 0.065 → 0.072 m in 4.4 s. The twist arrives, the network is selected, the joint targets are static. Ruled out: our command shape (identical to upstream's drive), the generated params, the keyframe, the real-time factor (1.00) and the viewer. test_sim_body_walks_forward_on_move is kept as a non-strict xfail sentinel — an XPASS after a re-pin means walking arrived.
• Upstream's own torch routing on Thor — every tier there ran on the local override, not as shipped.
• GPU training on Orin — no sm_87 kernels in the SBSA wheel.
• A real Hugging Face Jobs submission — the dry run proves the command shape and the tarball, nothing was submitted or billed.
• Multi-duck, the ether, cameras and ToF in sim — upstream marks them "designed and measured but not built" on this branch.

The tick engine

One process owns the control socket. robotd arbitrates nothing between clients, so a second process would be two authors fighting over every channel — hence one loop, one seam, riders composed onto it:

flowchart TB
  subgraph read ["1 · read — ONE snapshot per tick"]
    direction LR
    P["sense providers"] --> SN["Sense"]
  end
  subgraph decide ["2 · decide — pure, no I/O"]
    direction LR
    B["behaviours + rules<br/>one contribution each"] --> AR["arbitrate<br/>one owner per channel"] --> CO["compose the pose"]
  end
  subgraph write ["3 · write — exactly once"]
    direction LR
    HG{"human<br/>driving?"} -- "yes" --> WH["MOTION withheld"]
    HG -- "no" --> SK["TargetSink → robotd"]
  end
  read --> decide --> write --> TS["4 · tick_seam riders — after the write"]

Per tick, in this order: read one Sense; ask each live behaviour once; arbitrate a single owner per channel; compose; write through the sink exactly once; run the tick seam after the write; expire finished lifetimes; sleep to an absolute deadline. No wall-clock read anywhere in the loop — clock and sleep are injected, which is what makes a 500-tick run bit-for-bit reproducible in a test. A provider that raises degrades to None; a rider that raises is caught, counted and logged as a named drop while its siblings still run.

CLAUDE.md has the rest: the seam rules, how to add a verb or a noun, the error and output contracts, and the agent-first rubric CI enforces.

Cited from / built on

Nothing from these repositories is copied into this one. The CLI implements their documented commands and wire protocol and links to their docs — cite, don't import.

Upstream — the exact commits every verb is validated against are in docs/upstream-pins.md; re-pinning is one PR that moves all rows and re-runs the on-box verification.

AgentCulture siblings — this CLI is composed from three of them rather than inventing a fourth architecture.

Vendored skills under .claude/skills/ carry their provenance in docs/skill-sources.md.

Contributing

CLAUDE.md is the working agreement: CLI contracts, what to take from each sibling, version-bump-every-PR, the cicd PR lane, worktree layout, memory discipline.

uv sync
uv run pytest -n auto                          # 1101 tests
uv run teken cli doctor . --strict             # the agent-first rubric gate CI runs
markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"

License

Apache 2.0 — see LICENSE.