Command Reference (Generated)

This page is generated from the actual CLI implementation under raccoon/toolchain/. Do not edit by hand; update the CLI or the generator instead.

raccoon

Raccoon - Toolchain CLI for raccoon projects.

Usage: raccoon [OPTIONS] COMMAND [ARGS]...

Arguments & Options

  • --no-validate (flag) (default: False) Skip pre-command project validation.

Subcommands

  • raccoon calibrate Robot calibration.

 Run one calibration phase at a time: calibrate ticks calibrate autotune calibrate servos

  • raccoon checkpoint Manage invisible git checkpoints.
  • raccoon codegen Generate Python code from raccoon.project.yml.

Runs locally using the raccoon type index — no Pi connection needed.

  • raccoon connect Connect to a Raccoon Pi server at ADDRESS.

ADDRESS is the IP address or hostname of the Pi.

Examples: raccoon connect 192.168.4.1 raccoon connect raspberrypi.local raccoon connect 192.168.1.100 –port 8421

  • raccoon disconnect Disconnect from the current Raccoon Pi.
  • raccoon doctor Show system health: connection, tools, and package versions.
  • raccoon lcm LCM spy and debugging commands.

Spy on LCM traffic, record sessions, and playback recordings.

  • raccoon logs Browse and inspect libstp log runs.

Fetches logs from the connected Pi by default. Use –local to read logs from a local directory.

  • raccoon migrate Apply pending project migrations.

Reads format_version from raccoon.project.yml and applies all migration scripts with a higher NUMBER in order.

  • raccoon missions Create, remove, list, rename and reorder missions.
  • raccoon run Run codegen and then execute src.main.

If connected to a Pi, syncs the project and runs remotely. Use –local to force local execution.

The first positional argument may name a run configuration declared under run_configurations: in raccoon.project.yml (e.g. raccoon run dev). The configuration provides defaults for the flags below; explicit CLI flags still win.

Use –no-mN (e.g. –no-m0 –no-m2) to skip missions at those order indices.

  • raccoon shell Open an interactive SSH shell on the connected Pi.
  • raccoon sync Sync the current project with the connected Pi using rsync.

By default, pushes local files to the Pi (local -> Pi).

Use –push for explicit push (local -> Pi). Use –pull for pull (Pi -> local). Use –no-delete to keep extraneous files on the destination.

  • raccoon update Check for and install updates across all packages.

Uses the raccoon-image bundle manifest to determine target versions.

Examples: raccoon update # Stable bundle (bundles/latest.json) raccoon update –dev # Latest component tips (bundles/dev.json) raccoon update –bundle 2026.4.25.1 # Specific bundle raccoon update –check # Dry run, just show status

  • raccoon upload Preflight (validate → codegen → simulieren) und dann zum Roboter hochladen.

Jeder Schritt ist ein hartes Gate: der erste Fehler bricht ab, bevor irgendetwas den Roboter erreicht.

  • raccoon validate Check that config, mission files, and imports are consistent.
  • raccoon web Start the Web IDE with full backend support.

Serves the web IDE with a full API backend on a local port.

When run inside a project directory (containing raccoon.project.yml), the browser opens directly to that project.

Automatically opens the browser unless –no-open is specified.

Examples:

raccoon web              # Serve on port 4200

raccoon web -p 8080      # Serve on port 8080

raccoon web --no-open    # Don't auto-open browser

raccoon calibrate

Robot calibration.

 Run one calibration phase at a time: calibrate ticks calibrate autotune calibrate servos

Usage: raccoon calibrate [OPTIONS] COMMAND [ARGS]...

Arguments & Options

  • --local, -l (flag) (default: False) Run locally on this machine (requires hardware)

Subcommands

  • raccoon calibrate autotune Phase 2: run auto_tune() as a mission step.
  • raccoon calibrate servos Phase 3: jog servos to find named positions.
  • raccoon calibrate step-response Record a motor step response and plot BEMF vs time.
  • raccoon calibrate ticks Phase 1: measure encoder ticks/revolution.

raccoon calibrate autotune

Phase 2: run auto_tune() as a mission step.

Usage: raccoon calibrate autotune [OPTIONS]

raccoon calibrate servos

Phase 3: jog servos to find named positions.

Usage: raccoon calibrate servos [OPTIONS]

raccoon calibrate step-response

Record a motor step response and plot BEMF vs time.

Usage: raccoon calibrate step-response [OPTIONS]

Arguments & Options

  • --local (flag) (default: False) Run directly on this machine (requires hardware)
  • --ports (default: 0,1,2,3) Comma-separated motor ports to record
  • --mode (default: speed) speed = set_speed() [%%], velocity = set_velocity() [BEMF units, PID]
  • --speed (default: 70) Speed value (percent or BEMF units)
  • --duration (default: 3.0) Run duration in seconds
  • --brake-tail (default: 2.0) Extra seconds to record after braking
  • --hz (default: 100) Sample rate in Hz
  • --out (default: step_response.csv) CSV output filename
  • --plot (default: step_response.png) Plot output filename
  • --no-plot (flag) (default: False) Skip generating the plot

raccoon calibrate ticks

Phase 1: measure encoder ticks/revolution.

Usage: raccoon calibrate ticks [OPTIONS]

raccoon checkpoint

Manage invisible git checkpoints.

Usage: raccoon checkpoint [OPTIONS] COMMAND [ARGS]...

Subcommands

  • raccoon checkpoint clean Prune old checkpoints.
  • raccoon checkpoint delete Delete a single checkpoint.

IDENTIFIER is either the index number from ’list’ or a short SHA.

  • raccoon checkpoint list List all saved checkpoints.
  • raccoon checkpoint restore Apply a checkpoint to the working tree.

IDENTIFIER is either the index number from ’list’ or a short SHA.

  • raccoon checkpoint show Show the diff of a checkpoint.

IDENTIFIER is either the index number from ’list’ or a short SHA.

raccoon checkpoint clean

Prune old checkpoints.

Usage: raccoon checkpoint clean [OPTIONS]

Arguments & Options

  • --all (flag) (default: False) Delete all checkpoints
  • --older-than (default: 7) Delete checkpoints older than this many days

raccoon checkpoint delete

Delete a single checkpoint.

IDENTIFIER is either the index number from ’list’ or a short SHA.

Usage: raccoon checkpoint delete [OPTIONS] IDENTIFIER

Arguments & Options

  • IDENTIFIER (argument)

raccoon checkpoint list

List all saved checkpoints.

Usage: raccoon checkpoint list [OPTIONS]

raccoon checkpoint restore

Apply a checkpoint to the working tree.

IDENTIFIER is either the index number from ’list’ or a short SHA.

Usage: raccoon checkpoint restore [OPTIONS] IDENTIFIER

Arguments & Options

  • IDENTIFIER (argument)

raccoon checkpoint show

Show the diff of a checkpoint.

IDENTIFIER is either the index number from ’list’ or a short SHA.

Usage: raccoon checkpoint show [OPTIONS] IDENTIFIER

Arguments & Options

  • IDENTIFIER (argument)

raccoon codegen

Generate Python code from raccoon.project.yml.

Runs locally using the raccoon type index — no Pi connection needed.

Usage: raccoon codegen [OPTIONS]

Arguments & Options

  • --only (repeatable) (default: Sentinel.UNSET) Generate specific file(s): defs, robot. May be given multiple times.
  • --no-format (flag) (default: False) Skip black formatting
  • -o, --output-dir Override output directory (default: src/hardware/)
  • --no-validate (flag) (default: False) Skip pre-codegen validation checks.

raccoon connect

Connect to a Raccoon Pi server at ADDRESS.

ADDRESS is the IP address or hostname of the Pi.

Examples: raccoon connect 192.168.4.1 raccoon connect raspberrypi.local raccoon connect 192.168.1.100 –port 8421

Usage: raccoon connect [OPTIONS] ADDRESS

Arguments & Options

  • ADDRESS (argument)
  • --port, -p (default: 8421) Pi server port
  • --user, -u (default: pi) SSH username
  • --save, --no-save (flag) (default: True) Save connection to project config

raccoon disconnect

Disconnect from the current Raccoon Pi.

Usage: raccoon disconnect [OPTIONS]

raccoon doctor

Show system health: connection, tools, and package versions.

Usage: raccoon doctor [OPTIONS]

raccoon lcm

LCM spy and debugging commands.

Spy on LCM traffic, record sessions, and playback recordings.

Usage: raccoon lcm [OPTIONS] COMMAND [ARGS]...

Subcommands

  • raccoon lcm delete Delete an LCM recording from the Pi.
  • raccoon lcm list List available LCM recordings on the Pi.
  • raccoon lcm playback Playback a recorded LCM session.

Republishes recorded messages to LCM on the Pi.

Examples:

raccoon lcm playback my_session.jsonl

raccoon lcm playback test_run.jsonl --speed 2.0

raccoon lcm playback demo.jsonl --loop
  • raccoon lcm record Record LCM traffic to a file on the Pi.

Records are stored on the Pi and can be listed with ‘raccoon lcm list’.

Examples:

raccoon lcm record my_session

raccoon lcm record test_run --channel "SENSOR_*" --duration 60
  • raccoon lcm spy Spy on LCM traffic in real-time.

By default, shows all channels. Use –channel to filter.

Examples:

raccoon lcm spy

raccoon lcm spy --channel "SENSOR_*"

raccoon lcm spy --channel "MOTOR_CMD" --channel "SENSOR_DATA"

raccoon lcm spy --record my_session
  • raccoon lcm status Show current LCM spy/playback status.

raccoon lcm delete

Delete an LCM recording from the Pi.

Usage: raccoon lcm delete [OPTIONS] FILENAME

Arguments & Options

  • FILENAME (argument)
  • --yes, -y (flag) (default: False) Skip confirmation

raccoon lcm list

List available LCM recordings on the Pi.

Usage: raccoon lcm list [OPTIONS]

raccoon lcm playback

Playback a recorded LCM session.

Republishes recorded messages to LCM on the Pi.

Examples:

raccoon lcm playback my_session.jsonl

raccoon lcm playback test_run.jsonl --speed 2.0

raccoon lcm playback demo.jsonl --loop

Usage: raccoon lcm playback [OPTIONS] FILENAME

Arguments & Options

  • FILENAME (argument)
  • --speed, -s (default: 1.0) Playback speed multiplier
  • --loop, -l (flag) (default: False) Loop playback
  • --channel, -c (repeatable) (default: Sentinel.UNSET) Channel pattern to filter (supports wildcards)

raccoon lcm record

Record LCM traffic to a file on the Pi.

Records are stored on the Pi and can be listed with ‘raccoon lcm list’.

Examples:

raccoon lcm record my_session

raccoon lcm record test_run --channel "SENSOR_*" --duration 60

Usage: raccoon lcm record [OPTIONS] FILENAME

Arguments & Options

  • FILENAME (argument)
  • --channel, -c (repeatable) (default: Sentinel.UNSET) Channel pattern to filter (supports wildcards)
  • --duration, -d (default: 0) Recording duration in seconds (0 = until stopped)

raccoon lcm spy

Spy on LCM traffic in real-time.

By default, shows all channels. Use –channel to filter.

Examples:

raccoon lcm spy

raccoon lcm spy --channel "SENSOR_*"

raccoon lcm spy --channel "MOTOR_CMD" --channel "SENSOR_DATA"

raccoon lcm spy --record my_session

Usage: raccoon lcm spy [OPTIONS]

Arguments & Options

  • --channel, -c (repeatable) (default: Sentinel.UNSET) Channel pattern to filter (can specify multiple, supports wildcards)
  • --record, -r (default: Sentinel.UNSET) Record to file (filename)
  • --format, -f (default: table) Output format

raccoon lcm status

Show current LCM spy/playback status.

Usage: raccoon lcm status [OPTIONS]

raccoon logs

Browse and inspect libstp log runs.

Fetches logs from the connected Pi by default. Use –local to read logs from a local directory.

Usage: raccoon logs [OPTIONS] COMMAND [ARGS]...

Arguments & Options

  • --dir Path to a local .raccoon/runs/ directory (implies –local).
  • -n, --last Show last N runs.
  • -a, --all (flag) (default: False) Also include legacy rotated log files (from before the per-run scheme).
  • --local (flag) (default: False) Read local logs instead of fetching from Pi.

Subcommands

  • raccoon logs clear Delete all log files (on Pi or locally with –local).
  • raccoon logs download Download a run’s logs + the STM32 cmd_trace slice for that timeframe.

Bundles the selected run’s raw libstp log file together with the stm32-data-reader command trace (cmd_trace.jsonl) and the journald output of every service raccoon manages — the raccoon-server, the stm32-data-reader, and each service declared in raccoon.project.yml — all filtered to the run’s wall-clock time window, so a mission can be reconstructed offline for debugging.

RUN_ID is the run number from ‘raccoon logs’ (default: 1 = most recent).

  • raccoon logs services List project services and their journald output.

Only works against the connected Pi — project services are systemd units on the robot.

  • raccoon logs show Show log entries for a specific run.

RUN_ID is the run number from ‘raccoon logs’ (default: 1 = most recent).

  • raccoon logs sources List all log sources (files) seen in a run.
  • raccoon logs tail Show the most recent log lines, optionally following for new output.

Use -f to continuously watch for new log entries (requires –local).

raccoon logs clear

Delete all log files (on Pi or locally with –local).

Usage: raccoon logs clear [OPTIONS]

Arguments & Options

  • --yes, -y (flag) (default: False) Skip confirmation.

raccoon logs download

Download a run’s logs + the STM32 cmd_trace slice for that timeframe.

Bundles the selected run’s raw libstp log file together with the stm32-data-reader command trace (cmd_trace.jsonl) and the journald output of every service raccoon manages — the raccoon-server, the stm32-data-reader, and each service declared in raccoon.project.yml — all filtered to the run’s wall-clock time window, so a mission can be reconstructed offline for debugging.

RUN_ID is the run number from ‘raccoon logs’ (default: 1 = most recent).

Usage: raccoon logs download [OPTIONS] [RUN_ID]

Arguments & Options

  • RUN_ID (argument)
  • -o, --output Directory to write the bundle into (default: .raccoon/downloads/run<#>_
  • --pad (default: 2.0) Seconds of cmd_trace padding around the run’s time window.
  • --cmd-trace [–local only] Path to cmd_trace.jsonl (default: reader’s WOMBAT_CMD_TRACE / packaged path).

raccoon logs services

List project services and their journald output.

Only works against the connected Pi — project services are systemd units on the robot.

Usage: raccoon logs services [OPTIONS] COMMAND [ARGS]...

Subcommands

  • raccoon logs services show Show the last N journald entries for a project service.

raccoon logs services show

Show the last N journald entries for a project service.

Usage: raccoon logs services show [OPTIONS] SERVICE_NAME

Arguments & Options

  • SERVICE_NAME (argument)
  • -n, --lines (default: 200) Number of journal lines to fetch.
  • --no-pager (flag) (default: False) Don’t use a pager for output.

raccoon logs show

Show log entries for a specific run.

RUN_ID is the run number from ‘raccoon logs’ (default: 1 = most recent).

Usage: raccoon logs show [OPTIONS] [RUN_ID]

Arguments & Options

  • RUN_ID (argument)
  • -l, --level Filter by level (info, warn, error, …).
  • -s, --source Filter by source file substring.
  • -g, --grep Filter messages by regex.
  • --no-pager (flag) (default: False) Don’t use a pager for output.

raccoon logs sources

List all log sources (files) seen in a run.

Usage: raccoon logs sources [OPTIONS] [RUN_ID]

Arguments & Options

  • RUN_ID (argument)

raccoon logs tail

Show the most recent log lines, optionally following for new output.

Use -f to continuously watch for new log entries (requires –local).

Usage: raccoon logs tail [OPTIONS]

Arguments & Options

  • -n, --lines (default: 20) Number of lines to show initially.
  • -f, --follow (flag) (default: False) Follow the log file for new output (requires –local).
  • -l, --level Filter by level.
  • -s, --source Filter by source file substring.
  • -g, --grep Filter messages by regex.

raccoon migrate

Apply pending project migrations.

Reads format_version from raccoon.project.yml and applies all migration scripts with a higher NUMBER in order.

Usage: raccoon migrate [OPTIONS]

Arguments & Options

  • --target, -t Migrate to this version (default: latest)
  • --dry-run (flag) (default: False) Show pending migrations without applying them

raccoon missions

Create, remove, list, rename and reorder missions.

Usage: raccoon missions [OPTIONS] COMMAND [ARGS]...

Subcommands

  • raccoon missions create Create a new mission in the current project.

NAME must start with the mission number, e.g. M030Wave (creates M030WaveMission). M000 and M999 are reserved for setup/shutdown.

  • raccoon missions list List the missions of the current project.
  • raccoon missions remove Remove a mission from the current project.

NAME is the mission name or just its number (e.g. Drive, M010Drive or M010).

  • raccoon missions rename Rename a mission to NEW_NAME (the M-number is kept).

NAME is the mission name or just its number (e.g. Drive, M010Drive or M010).

  • raccoon missions reorder Reorder the missions of the current project.

Without arguments an interactive list opens (setup/shutdown stay pinned). With arguments the new order is given directly:

 By index (1-based): raccoon missions reorder 1 3 2 By name (M-prefix / Mission suffix optional, unique prefixes allowed): raccoon missions reorder Setup Drive Collect Shutdown

All missions are renumbered M010, M020, M030 … afterwards.

raccoon missions create

Create a new mission in the current project.

NAME must start with the mission number, e.g. M030Wave (creates M030WaveMission). M000 and M999 are reserved for setup/shutdown.

Usage: raccoon missions create [OPTIONS] NAME

Arguments & Options

  • NAME (argument)

raccoon missions list

List the missions of the current project.

Usage: raccoon missions list [OPTIONS]

raccoon missions remove

Remove a mission from the current project.

NAME is the mission name or just its number (e.g. Drive, M010Drive or M010).

Usage: raccoon missions remove [OPTIONS] NAME

Arguments & Options

  • NAME (argument)
  • --keep-file (flag) (default: False) Only remove it from the config, keep the mission file.

raccoon missions rename

Rename a mission to NEW_NAME (the M-number is kept).

NAME is the mission name or just its number (e.g. Drive, M010Drive or M010).

Usage: raccoon missions rename [OPTIONS] NAME NEW_NAME

Arguments & Options

  • NAME (argument)
  • NEW_NAME (argument)

raccoon missions reorder

Reorder the missions of the current project.

Without arguments an interactive list opens (setup/shutdown stay pinned). With arguments the new order is given directly:

 By index (1-based): raccoon missions reorder 1 3 2 By name (M-prefix / Mission suffix optional, unique prefixes allowed): raccoon missions reorder Setup Drive Collect Shutdown

All missions are renumbered M010, M020, M030 … afterwards.

Usage: raccoon missions reorder [OPTIONS] [ORDER]...

Arguments & Options

  • ORDER... (argument)

raccoon run

Run codegen and then execute src.main.

If connected to a Pi, syncs the project and runs remotely. Use –local to force local execution.

The first positional argument may name a run configuration declared under run_configurations: in raccoon.project.yml (e.g. raccoon run dev). The configuration provides defaults for the flags below; explicit CLI flags still win.

Use –no-mN (e.g. –no-m0 –no-m2) to skip missions at those order indices.

Usage: raccoon run [OPTIONS] [ARGS]...

Arguments & Options

  • ARGS... (argument)
  • --dev (flag) (default: False) Dev mode: use button instead of wait-for-light
  • --local, -l (flag) (default: False) Force local execution (skip remote)
  • --no-sync (flag) (default: False) Skip syncing before remote run
  • --no-calibrate (flag) (default: False) Skip calibration steps, use stored values
  • --no-codegen (flag) (default: False) Skip code generation (used by server when codegen was done client-side)
  • --no-checkpoints (flag) (default: False) Skip waiting for time checkpoints (wait_for_checkpoint steps return immediately)
  • --debug (flag) (default: False) Enable debug mode: breakpoint() steps pause and wait for a button press (otherwise no-op).
  • --record-localization (flag) (default: False) Record particle-filter state to .raccoon/runs/<run_id>/localization.jsonl (off by default).
  • --no-record (flag) (default: False) Force-disable localization recording (redundant now that recording is off by default; kept for compatibility).
  • --no-profile (flag) (default: False) Disable step profiling for this run (profiling is on by default).
  • --record-hz Localization recorder downsample rate in Hz (default 20).
  • --record-sensors, --no-record-sensors (flag) (default: True) Record raw SHM sensor channels to .raccoon/runs/<run_id>/sensors.mcap on the Pi for the duration of the run (on by default).
  • --raw (flag) (default: False) Local runs: inherit the program’s stdout directly instead of the live JSONL log viewer.

raccoon shell

Open an interactive SSH shell on the connected Pi.

Usage: raccoon shell [OPTIONS]

raccoon sync

Sync the current project with the connected Pi using rsync.

By default, pushes local files to the Pi (local -> Pi).

Use –push for explicit push (local -> Pi). Use –pull for pull (Pi -> local). Use –no-delete to keep extraneous files on the destination.

Usage: raccoon sync [OPTIONS]

Arguments & Options

  • --push (flag) (default: False) Push-only: upload local files to Pi
  • --pull (flag) (default: False) Pull-only: download files from Pi to local
  • --delete, --no-delete (flag) (default: True) Delete extraneous files on destination (default: on)
  • --verbose, -v (flag) (default: False) Print detailed per-file sync actions
  • --no-validate (flag) (default: False) Skip pre-sync validation checks for push syncs.

raccoon update

Check for and install updates across all packages.

Uses the raccoon-image bundle manifest to determine target versions.

Examples: raccoon update # Stable bundle (bundles/latest.json) raccoon update –dev # Latest component tips (bundles/dev.json) raccoon update –bundle 2026.4.25.1 # Specific bundle raccoon update –check # Dry run, just show status

Usage: raccoon update [OPTIONS]

Arguments & Options

  • --check (flag) (default: False) Only check, don’t install
  • --laptop-only (flag) (default: False) Only update laptop packages
  • --pi-only (flag) (default: False) Only update Pi packages
  • --force (flag) (default: False) Force reinstall even if versions match
  • --bundle Pin to a specific bundle
  • --dev (flag) (default: False) Use the dev manifest (latest component tips, auto-updated by CI)
  • --allow-missing-pypi-version-fallback (flag) (default: False) If the requested bundle version is missing on PyPI, install the latest available PyPI release instead.

raccoon upload

Preflight (validate → codegen → simulieren) und dann zum Roboter hochladen.

Jeder Schritt ist ein hartes Gate: der erste Fehler bricht ab, bevor irgendetwas den Roboter erreicht.

Usage: raccoon upload [OPTIONS]

Arguments & Options

  • --skip-sim (flag) (default: False) Runtime-Simulation überspringen (umgeht das Gate — nur für Notfälle).
  • --no-start-check (flag) (default: False) Programm nach dem Sync nicht auf dem Roboter starten/prüfen.
  • --sim-timeout (default: 180.0) Timeout für den Simulationslauf in Sekunden.
  • --start-timeout (default: 8.0) Wie lange auf den Programmstart am Roboter gewartet wird (Sekunden).
  • --no-python-compile (flag) (default: False) Python-Bytecode-Compile-Checks in der Validierung überspringen.

raccoon validate

Check that config, mission files, and imports are consistent.

Usage: raccoon validate [OPTIONS]

Arguments & Options

  • --no-python-compile (flag) (default: False) Skip Python bytecode compile checks for project source files.
  • --no-defs-check (flag) (default: False) Skip checking Defs. accesses against the defined hardware.

raccoon web

Start the Web IDE with full backend support.

Serves the web IDE with a full API backend on a local port.

When run inside a project directory (containing raccoon.project.yml), the browser opens directly to that project.

Automatically opens the browser unless –no-open is specified.

Examples:

raccoon web              # Serve on port 4200

raccoon web -p 8080      # Serve on port 8080

raccoon web --no-open    # Don't auto-open browser

Usage: raccoon web [OPTIONS]

Arguments & Options

  • --port, -p (default: 4200) Port to serve on
  • --no-open (flag) (default: False) Don’t open browser automatically
Written by Docs Bot
← missions