# Interactive Commands in Rustlings Watch Mode: Complete Keyboard Reference

> Master Rustlings watch mode with eight interactive commands. Navigate exercises, get hints, reset progress, and control flow all from your keyboard.

- Repository: [The Rust Programming Language/rustlings](https://github.com/rust-lang/rustlings)
- Tags: api-reference
- Published: 2026-03-05

---

**Rustlings watch mode provides eight keyboard-driven interactive commands that let you navigate exercises, display hints, reset progress, and control execution flow without leaving the terminal.**

The `rust-lang/rustlings` CLI tool offers an interactive learning environment where beginners practice Rust through hands-on exercises. When you launch `rustlings watch`, the program enters an event-driven loop that translates keyboard input into actions via the `InputEvent` enum defined in the source code. Understanding these interactive commands helps you navigate the curriculum efficiently and troubleshoot compilation errors faster.

## How Rustlings Watch Mode Handles Keyboard Input

The watch mode architecture separates terminal input handling from business logic through a channel-based event system. When you press a key, the raw signal travels through two main components before executing your intended action.

### Terminal Event Mapping in [`terminal_event.rs`](https://github.com/rust-lang/rustlings/blob/main/terminal_event.rs)

The [`src/watch/terminal_event.rs`](https://github.com/rust-lang/rustlings/blob/main/src/watch/terminal_event.rs) file contains the `terminal_event_handler` function that reads raw `crossterm` events and filters out key repeats or releases. It maps specific character codes to `InputEvent` variants and sends them through an asynchronous channel.

According to the source code, the handler checks a global `EXERCISE_RUNNING` atomic boolean to prevent processing input while an exercise is compiling or executing. This ensures keyboard commands do not interrupt active build processes.

### The Watch Loop in [`watch.rs`](https://github.com/rust-lang/rustlings/blob/main/watch.rs)

The main watch loop in [`src/watch.rs`](https://github.com/rust-lang/rustlings/blob/main/src/watch.rs) receives `WatchEvent::Input` values and delegates to `WatchState` methods based on the embedded `InputEvent` variant. For example, when the loop detects `InputEvent::Next`, it invokes `watch_state.next_exercise()` to advance the curriculum index or terminate if all exercises are complete.

This separation of concerns allows the interactive commands to remain consistent regardless of whether the user triggered them via keyboard input or file system notifications.

## Complete List of Interactive Commands in Rustlings Watch Mode

The following keyboard shortcuts are available while `rustlings watch` is running. Each command maps to a specific `InputEvent` variant processed by the watch loop.

| Key | `InputEvent` Variant | Function | Availability |
|-----|---------------------|----------|--------------|
| **`n`** | `Next` | Advances to the next exercise or exits if the curriculum is complete | Always active |
| **`r`** | `Run` | Re-runs the current exercise manually | Only when started with `--manual-run` flag |
| **`h`** | `Hint` | Displays the hint text for the current exercise in the terminal | Always active |
| **`l`** | `List` | Exits watch mode temporarily, shows the exercise list, then returns to watch mode | Always active |
| **`c`** | `CheckAll` | Automatically runs all remaining exercises sequentially without further input | Always active |
| **`x`** | `Reset` | Clears the current exercise file to its original state after user confirmation | Always active |
| **`q`** | `Quit` | Terminates the Rustlings process immediately with a goodbye message | Always active |

The **`r`** command requires special attention. When you start watch mode with `rustlings watch --manual-run`, the automatic file-watching behavior is disabled. This mode is useful on slower file systems or when you want precise control over when compilation occurs. In this configuration, pressing `r` triggers the `Run` event, which executes `watch_state.run_current_exercise()`.

## Using Interactive Commands: Practical Examples

### Standard Watch Mode Workflow

In the default configuration, Rustlings automatically compiles exercises when you save changes. Use these commands to navigate efficiently:

```bash

# Start the interactive learning environment

rustlings watch

```

Once running:
- Press **`n`** after successfully compiling an exercise to advance to the next challenge
- Press **`h`** if you encounter a compiler error and need guidance
- Press **`x`** if your code becomes too messy and you want to start fresh with the original template

### Manual Run Mode for Controlled Execution

On systems with slow file system notifications, or when you want to prevent automatic compilation:

```bash

# Start with manual control over compilation

rustlings watch --manual-run

```

In this mode:
- Edit your exercise file in another terminal or editor
- Return to Rustlings and press **`r`** to compile and test your changes
- Use **`n`**, **`h`**, and other commands normally

This workflow prevents the watcher from triggering builds during incomplete edits, reducing CPU usage and terminal noise.

## Key Implementation Details

The interactive command system relies on several implementation details that ensure responsiveness and safety:

**Input Blocking During Compilation**
The global `EXERCISE_RUNNING` atomic boolean, defined in the watch module, prevents the terminal event handler from sending input events while an exercise is compiling. This protects against race conditions where a user might press `n` to skip an exercise while the previous one is still building.

**Event Channel Architecture**
Commands flow through an async channel as `WatchEvent::Input(InputEvent::Variant)` structures. This decouples the terminal input thread from the main watch loop, allowing the UI to remain responsive even during long-running compilations.

**State Management**
The `WatchState` struct in [`src/watch/state.rs`](https://github.com/rust-lang/rustlings/blob/main/src/watch/state.rs) maintains the current exercise index and hint visibility status. When the watch loop receives a command like `InputEvent::Reset`, it delegates to `watch_state.reset_exercise()`, which handles the file I/O and user confirmation prompts.

## Summary

- Rustlings watch mode provides **eight interactive keyboard commands** (`n`, `r`, `h`, `l`, `c`, `x`, `q`) that control exercise navigation, execution, and state management.
- The **`r` (Run) command** only activates when starting with `--manual-run`, allowing manual triggering of compilation on slower systems.
- Input handling occurs in [`src/watch/terminal_event.rs`](https://github.com/rust-lang/rustlings/blob/main/src/watch/terminal_event.rs), while command execution logic resides in [`src/watch.rs`](https://github.com/rust-lang/rustlings/blob/main/src/watch.rs), creating a clean separation between event detection and state manipulation.
- The system uses an `EXERCISE_RUNNING` atomic flag to prevent command processing during active compilation, ensuring stable execution.

## Frequently Asked Questions

### What is the difference between `rustlings watch` and `rustlings watch --manual-run`?

Standard `rustlings watch` automatically compiles and tests your code whenever you save changes to the exercise file. The `--manual-run` flag disables this automatic behavior, requiring you to press **`r`** to trigger compilation manually. Use manual-run mode on systems with slow file system notifications or when you want to prevent builds during incomplete edits.

### How do I reset an exercise if I make too many mistakes?

Press **`x`** while in watch mode to trigger the reset command. This sends an `InputEvent::Reset` to the watch loop, which invokes `watch_state.reset_exercise()`. The system will prompt you for confirmation before clearing your current code and restoring the original exercise template from [`src/watch/state.rs`](https://github.com/rust-lang/rustlings/blob/main/src/watch/state.rs).

### What happens when I press `c` to check all exercises?

Pressing **`c`** sends an `InputEvent::CheckAll` event that triggers `watch_state.check_all_exercises()`. This command automatically runs through all remaining exercises in the curriculum sequentially without requiring further keyboard input. It is useful for verifying your progress or batch-testing solutions after completing multiple exercises.

### Why can't I use the `r` key to rerun exercises in standard watch mode?

The **`r`** (Run) command is conditionally mapped in [`src/watch/terminal_event.rs`](https://github.com/rust-lang/rustlings/blob/main/src/watch/terminal_event.rs) only when the `manual_run` configuration flag is `true`. In standard watch mode, this mapping is disabled because the system automatically runs exercises on file changes. Attempting to press `r` in standard mode will not trigger an `InputEvent::Run` because the terminal handler filters out this key binding when `manual_run == false`.