Command configuration

How the teleop, gravity-comp, waypoints, collect-data, collect-dagger, replay-dataset, run-policy, and inference-server commands are configured with draccus.

Eight commands — teleop, gravity-comp, waypoints, collect-data, collect-dagger, replay-dataset, run-policy, and inference-server — expose their entire configuration through draccus instead of a fixed set of argparse flags. Every field of the underlying config dataclass is reachable from the command line, and the whole config can also be loaded from a file.

This page covers the syntax. Each operation mode has its own Config Parameters page listing every field with its default: Teleoperation, Gravity Compensation, Data Collection, Replay Dataset, Run Policy, and DAgger Collection. waypoints and inference-server list their flags on their own CLI pages.

The remaining commands (can.*, motor.*, zed.*, gst.*, jetson.setup, provision, tune.*, and serve) still use plain argparse flags and are unaffected by anything on this page.

Three ways to set any field

Dotted CLI overrides

Override any nested field with --dotted.path VALUE, e.g. --axol.left.elbow.kp 60.

Whole-config file

Load a complete JSON/YAML config with --config_path run.json, then layer CLI overrides on top.

Shared settings file

Save a value once in the control panel (~/.almond/settings.json) and every operation — panel, CLI, or SDK — uses it by default.

The shared settings file

The robot has one settings file, ~/.almond/settings.json ($ALMOND_HOME/settings.json), edited by the control panel. The same file is read by default by every draccus command on this page and by the SDK constructors, so arm stiffness, per-joint gains and link masses, gripper limits, teleop rates and rest poses, CAN adapters — anything saved once — apply identically whether you drive the robot from the browser, the terminal, or Python.

The file uses the same vocabulary as a --config_path file: it is a nested tree whose axol, teleop, kinematics, jelly and vr_server sections are the config dataclasses themselves, plus a few sections for operation-level knobs (robot for the CAN channels, gravity, recording, inference, …). For axol teleop the file is literally a partial teleop config; the other commands embed the same subsystems at their own paths and the translation is automatic. See the Settings File page for the layout.

{
  "version": 2,
  "axol": { "left_stiffness": 0.8, "left": { "elbow": { "kp": 60 } } },
  "teleop": { "frequency": 240 },
  "robot": { "left_channel": "can0", "right_channel": "null" }
}

Two flags control it on every draccus command:

Flag	Effect
--settings_path PATH	Read another settings file (the same file the control panel’s Export writes) instead of ~/.almond/settings.json.
--no_settings	Ignore the settings file; run the built-in (calibrated) defaults plus whatever you pass explicitly.

axol teleop                                  # panel settings apply
axol gravity-comp --kd 1.0                   # panel settings, kd overridden
axol teleop --settings_path bench.json       # a different robot's settings
axol teleop --no_settings --axol.left_stiffness 0.8   # built-in defaults only

A missing ~/.almond/settings.json is fine (a fresh host runs the built-in defaults), but a file that exists and cannot be read — corrupt JSON, a permission problem, a symlink in its path — is a usage error, not a silent fallback: the command refuses to start rather than run a different robot’s numbers. Fix the file, or pass --no_settings to run without it. The same applies to the SDK (Axol(), Mantis(), Jelly(), VRTeleop() raise). Only axol serve tolerates an unreadable file, so the control panel can come up for you to repair it.

Dotted overrides

Each command is backed by a config dataclass (for example TeleopCmdConfig wraps the full AxolConfig). Nest into it with dots:

axol teleop --axol.left_stiffness 0.8
axol teleop --axol.left.elbow.kp 60 --axol.right.gripper.torque_limit 0.7
axol teleop --axol.has_gripper false   # gripperless SKU
axol collect-data --repo_id myorg/pick --task "pick" \
    --robot_config.axol_config.left_stiffness 0.8 \
    --robot_config.cameras "{overhead: {serial: 41234567}, left_arm: {serial: 41234568}, right_arm: {serial: 41234569}}"

Any field you don’t override keeps its default — overriding --axol.left.elbow.kp leaves every other per-joint gain at its tuned default.

Config files

axol teleop --config_path my_teleop.json
axol run-policy --config_path rollout.yaml --device cpu   # file, then override

Precedence is defaults → shared settings file → --config_path file → CLI flags (later wins), so flags always override file values, which override the robot’s saved settings, which override the built-in defaults. Operations launched from the control panel resolve in exactly the same order, so a direct CLI run and a panel-launched one agree on every value neither of you overrode.

Same knob, different path

Each command embeds the shared subsystem configs at its own dotted path — arm stiffness is axol.left_stiffness on teleop but robot_config.axol_config.left_stiffness on collect-data. Each mode’s Config Parameters page spells its keys with the right prefix for that command.

On a calibrated robot the “defaults” already include that robot’s own measurements, layered in this order (later wins): the coded constants ← the factory calibration fetched from the cloud by calibration.pull (~/.almond/factory_calibration.json) ← per-joint gains, friction parameters, and link centres of mass and masses saved locally by tune.pid --save / tune.friction --save / tune.gravity --save to ~/.almond/calibration.json. All are loaded into AxolConfig at construction; config files and CLI flags still override them like any other default.

Field-name conventions

Convention	Form	Example
Field names use underscores, not dashes	--field_name	--log_level DEBUG, --teleop_hz 120
Nested fields are dot-separated	--a.b.c	--axol.left.gripper.torque_limit 0.7
None is written null	--field null	--left_channel null (disable the left arm)
Lists use bracket syntax	[a,b,c]	--free_joints [SHOULDER_1,WRIST_3]
Dict fields take one inline YAML/JSON value (dotted paths can’t reach inside a dict)	--field "{k: v}"	--cameras "{overhead: 41234567}" (teleop); --robot_config.cameras "{overhead: {serial: 41234567}}" (collect-data / run-policy)
Booleans take an explicit value	--flag true	--push_to_hub true
Shared settings selectors (every draccus command)	--settings_path PATH, --no_settings	--no_settings (built-in defaults only)

Booleans are value-taking under draccus (--push_to_hub true, not a bare --push_to_hub). The one exception is teleop’s --sim, which is normalized so a bare --sim works as well as --sim true.

Validation

Choice fields (e.g. --log_level, --policy_type, --aggregate_fn) are validated against their allowed values, and missing required fields or type mismatches are reported as a clean usage error rather than a traceback.

axol <command> --help lists only the common fields (top-level options plus stiffness and gripper limits) to keep the output readable — the deeply-nested per-joint gains are hidden but remain fully overridable with their dotted paths (e.g. --axol.left.elbow.kp). This page is the complete reference for the override syntax; each mode’s Config Parameters page (e.g. Teleoperation) is the complete list of fields.