> Documentation index: https://nao-rs.lukaloehr.com/llms.txt, a list of every page in this documentation.

# Command-line tools

> naoctl on the robot and the nao-rs CLI on your computer, every command and what it touches.

## naoctl (on the robot)

`naoctl` is installed with the robot bundle at `/home/nao/hulk/bin/naoctl`.
Run it on the robot as the `nao` user.

### Death switch

These three work at any time, also while `hulk` runs. They only touch the
death switch page.

| Command | What it does |
| --- | --- |
| `naoctl status` | Prints whether the switch is armed or tripped, why and for how long, and the runtime's heartbeat: process id, cycle, age of the last beat, last all-off cycle |
| `naoctl stop` | Trips the switch (reason `Cli`) and prints the status |
| `naoctl rearm` | Re-arms the switch. Only after a person has checked the robot. The robot stays limp until the app or an API wakes it |

```text
$ naoctl status
armed: motors may move
driver: pid 812, cycle 52210, last beat 2.7 ms ago, last all-off cycle 0
```

### Hardware commands

These open the chest board or the head bus themselves, so whatever else
drives them must be stopped first: `systemctl stop hulk` on nao-rs, or HAL
(and LoLA for the head) on the original stack. Stop the guard too
(`sudo systemctl stop nao-rs-guard`) for `guard`.

| Command | What it does |
| --- | --- |
| `naoctl prefs` | Starts the link, reads the chest board preferences and prints every key and value, with the size, CRC and time taken |
| `naoctl run [seconds]` | Runs the whole runtime (chest board in HAL's order, head bus, fan, death switch) for 10 seconds or the given time. Sets the chest blue, the eyes green and the sonar on, and prints the state twice a second. Boards are accepted as HAL 2.8.5 does, so the motors stay off |
| `naoctl guard [seconds]` | Runs the guard (what `nao-rs-guard` runs) for 30 seconds or the given time and prints its events |
| `naoctl head [seconds]` | Runs the head driver: eyes cycle red, green and blue, ears and skull on; prints touch, power and face temperature |
| `naoctl replay-sensors <hal.log> [frames]` | Sends the frames of a HAL recording, byte for byte, through the link and decodes the robot's real answers |

`naoctl` reads the death switch path from `NAO_RS_DEATHSWITCH` when it is set
(default `/run/nao-rs/deathswitch`).

## nao-rs (on your computer)

The `nao-rs` CLI is part of the nao-rs repository. Run it from a checkout as
`cargo nao-rs <command>`; it needs `ssh` and `scp`, and an x86_64 Linux host
with Docker for robot builds.

| Command | What it does |
| --- | --- |
| `nao-rs stop <address>` | **Death switch.** Sends the UDP stop to the guard on port 7701, ten times 5 ms apart. Works when `hulk` is stuck. Re-arm on the robot |
| `nao-rs robot build [--host <host>]` | Builds `dist/nao-rs-robot.tar.gz` (`hulk`, `nao-rs-guard`, `naoctl`, units, installer) in HULKs' NAO SDK container on `<host>` (default `atlas`) |
| `nao-rs robot install <address> [--bundle <file>]` | Installs the bundle on a robot running HULKs-OS, with health check and automatic rollback. See [Install](https://nao-rs.lukaloehr.com/get-started/install.md) |
| `nao-rs robot restore <address>` | Removes nao-rs and brings back HAL, LoLA and HULA |
| `nao-rs agent tools <agent-id> [--mode agent\\|live] [--dry-run]` | Adds or updates nao-rs's client tools on your ElevenLabs agent; never touches its prompt, voice or model. See [Voice agent](https://nao-rs.lukaloehr.com/brain/voice-agent.md) |
| `nao-rs app [--webots <path>]` | Builds the macOS app with the simulator |
| `nao-rs release <version> [--host <host>]` | Builds the app and the robot bundle and publishes them as a GitHub release |

The installer connects as `nao` with the default password `nao`.

## Chest board and fan tools

Ports of Aldebaran's `chest-version`, `chest-mode`, `chest-harakiri`,
`alfand` and `fanspeed`, plus a read-only `faninfo`, are built from the drivers
repository; they are not in the robot bundle yet. See [Chest board
link](https://nao-rs.lukaloehr.com/hardware/chest-board.md#the-chest-board-tools) and [Temperatures, fan and
thermal protection](https://nao-rs.lukaloehr.com/safety/thermal.md#fan-tools).

## Related topics

- [Reference](https://nao-rs.lukaloehr.com/reference.md)
- [Robot API](https://nao-rs.lukaloehr.com/reference/api.md)
- Previous: [Robot API](https://nao-rs.lukaloehr.com/reference/api.md)
- Next: [Troubleshooting](https://nao-rs.lukaloehr.com/help/troubleshooting.md)