CLI reference

arc is the one command on the robot computer. Activate the Python environment first, in every new shell:

source ~/arc_env/bin/activate

arc --help starts with the list of commands:

usage: arc run [CONFIG] [--log-dir DIR | --no-log] [relay flags...]
       arc doctor [CONFIG] [--identify] [relay flags...]
       arc setup [--output PATH] [--force] [--template PATH]
                 [--answers FILE] [--non-interactive]
       arc lagdiag LOG|LOG_DIR
       arc enroll [KEY] [--name NAME] [--backend BACKEND] [--yes]
       arc config status|sync|pull [CONFIG] [relay flags...]
       arc --version

CONFIG is the path of a robot.toml. When it is left out, ./robot.toml is used, so run the commands from the directory that holds the file. A message from a command starts with [arc]. A message from the running client starts with [yam-relay], whatever the arm type.

arc enrollCopy Anchor Link

Registers this robot in your account and stores its identity in ~/.config/arc/identity/. See Enroll.

usage: arc enroll
       arc enroll KEY [--name NAME] [--backend BACKEND] [--yes]

arc enroll with nothing after it is the usual way: it asks for the key, the robot's name and the arm type, shows a summary and asks before it enrolls. arc enroll KEY is the form for a script.

Exit code 0 when the robot is enrolled, 1 otherwise. Nothing is written when enrollment fails.

arc setupCopy Anchor Link

Writes robot.toml for this robot, one step at a time. See Configure your robot.

usage: arc setup [-h] [--output PATH] [--force] [--template PATH]
                 [--backend {yam,makermods}] [--relay-config FILE]
                 [--answers FILE] [--non-interactive]

The steps, as arc setup --help lists them:

steps, in order:
  cameras  find the cameras, save a snapshot of each, assign roles
  arms     list the CAN buses that are up, ask which is the left arm
  relay    nothing to ask on an enrolled robot (arc enroll); otherwise relay host, CA cert path and robot id, and the robot's identity cert
  review   every value and where it came from, then confirm
  write    write the file, blanks included and named; an existing file is kept as .bak

arc doctorCopy Anchor Link

Checks what arc run with the same arguments would use, and starts nothing. It prints one line per check and a summary, and exits with code 1 if any check failed.

Each line is PASS, WARN, FAIL or SKIP, the name of the check, and a detail. SKIP means the check does not apply here, for example the arm address check on a robot with CAN arms. A FAIL line says what is missing and, where there is one, the command that fixes it.

The config sync line on a robot whose file matches the console's copy:

[arc] PASS  config sync: in sync

On an enrolled robot doctor asks Northstar for that one state and changes nothing. It makes no other connection.

Do not run --identify while arc run is running. It refuses when another client holds the lock. See Troubleshooting for what to do about a failed check.

arc runCopy Anchor Link

Checks that the robot can start, then starts the client: it opens the arms and the cameras, connects to the relay and waits for an operator. It runs until it is stopped. Ctrl+C stops it.

Before it starts anything, run stops with a one-line error if the file is missing or has a blank value, if the robot is not enrolled, or if another arc run is already running on this computer. A CAN link that is down is a warning with the command that brings it up. The client then keeps trying that arm until it opens.

On an enrolled robot run syncs robot.toml with the console first. See how settings sync.

Every other option overrides one value of robot.toml for this run. The file is not changed. The ones you may need:

arc run --help prints every option, including the connection options (--relay-host, --relay-cert and others). An enrolled robot gets those values from its identity, so leave them out.

Every run writes a session log, one file per start, to logs/ next to CONFIG. Its path is the first line printed:

[arc] Session log: ~/robot/logs/arc-20261007-214853-98807.log

The log holds everything the terminal shows and is readable only by your user. Old logs are not deleted.

arc config statusCopy Anchor Link

Shows whether robot.toml and the console's copy match, and whether a change from the console is waiting. Changes nothing.

arc config --help describes the three config commands:

usage: arc config status [CONFIG] [relay flags...]
       arc config sync   [CONFIG] [relay flags...]
       arc config pull   [CONFIG] [relay flags...]

  The console keeps a copy of this robot's robot.toml. Only a robot that
  uses its enrolled identity (arc enroll, [relay] cert blank) syncs.
  CONFIG is a robot.toml (default: ./robot.toml), as for arc run.

  status  the local hash, the hash and time of the synced copy, and whether
          a change made in the console is waiting. Changes nothing.
  sync    upload the local file now. It becomes the copy the console shows.
  pull    what arc run does at each start, without starting: upload
          when the file changed, or write a waiting change into robot.toml
          (the old file is kept as robot.toml.<date>-<time>.bak).

arc config status

[arc] config: ~/robot/robot.toml
[arc] local hash: 9c3534ec...
[arc] baseline hash: 9c3534ec..., synced 2026-10-08T02:47:58.254604+00:00
[arc] pending change: none
[arc] state: in sync

The hashes are shortened here. With a change waiting, the fourth line names it:

[arc] pending change: 8e2dc98d-c310-4e0e-9cee-ca1e304f597b, 2 setting(s), made 2026-10-08T02:48:19.754299+00:00
[arc] state: a change is waiting for the next start

Configure your robot lists the four states. Exit code 0, or 1 when the state could not be read.

The three config commands work on a robot that uses its enrolled identity. On a robot that was set up before enrollment they print one line saying that its settings are not synced.

arc config syncCopy Anchor Link

Uploads robot.toml now. It becomes the copy the console shows.

arc config sync

[arc] config sync: settings uploaded (9c3534ec...), synced 2026-10-08T02:47:58.254604+00:00

If a change from the console was waiting and no longer fits the file, a second line says that it now needs review in the console. Exit code 0 when the file was uploaded, 1 otherwise.

arc config pullCopy Anchor Link

Does what arc run does at each start, without starting: uploads the file if it changed, or writes a waiting change from the console into robot.toml. The old file is kept as robot.toml.<date>-<time>.bak.

arc config pull

With nothing to do:

[arc] config sync: in sync (9c3534ec7970)

With a change waiting:

[arc] config sync: applied 2 changes from the console to ~/robot/robot.toml (relay.record_fps = 20, relay.record_stream = true); the old file is kept as ~/robot/robot.toml.20261007-214820.bak

Exit code 1 when Northstar could not be asked, 0 otherwise. A change that was refused or that no longer fits the file is reported in one line and the exit code is still 0. Use arc config status to read the state in a script.

Run it while arc run is stopped. A running client read the file when it started and does not read it again.

arc lagdiagCopy Anchor Link

Summarizes the timing lines of a session log. While it runs, the client prints one line per second that starts with [diag:loop]. lagdiag reads them and prints one row per measurement.

usage: arc lagdiag RELAY_LOG|LOG_DIR

arc lagdiag logs/

The first rows, from a ten second log with nobody driving:

log: logs/arc-20261007-214853-98807.log
10 [diag:loop] lines (one per second). worst is min for ctrl_pps and *_hz; for the rest it is max.
field                     median       min       max      n     worst
lag_p50_ms                   0.5       0.4       0.6     10       0.6
lag_p99_ms                   3.1       2.6      22.5     10      22.5
lag_max_ms                   3.1       2.6      22.5     10      22.5

More rows follow, one per field. na means there was no sample, for example no commands while nobody is driving.

<side> is right or left. Northstar may ask for this output when a session feels slow.

arc --versionCopy Anchor Link

Prints arc and the installed version. -V does the same.

FilesCopy Anchor Link

Paths that start with ./ are next to robot.toml.

arc run also holds a lock file, arc-robot.lock, in $XDG_RUNTIME_DIR (or in an arc-<uid> directory under the system's temporary directory) while it runs. The lock is released when the process ends, also after a crash.

Environment variablesCopy Anchor Link