Command Line Interface

Relevant source files

• src/app_state.rs
• src/cli.rs
• src/editor.rs
• src/editor/zellij.rs
• src/exercise.rs
• src/main.rs
• src/run.rs

The Command Line Interface (CLI) is the primary entry point for Rustlings. It handles user input via subcommands and flags, manages the application lifecycle, and orchestrates the transition between different execution modes (like watch mode and list mode).

Command Structure

Rustlings utilizes the clap crate to define its interface. The CLI is divided into global arguments and specific subcommands that dictate the application's behavior.

Global Arguments and Flags

Global flags affect how Rustlings interacts with the user's environment, particularly regarding editor integration and execution monitoring.

Flag	Description
--no-editor	Disables the automatic opening of exercise files.
--edit-cmd <CMD>	Specifies a custom command to open exercises (e.g., code, vim).
--manual-run	Disables automatic file-watch triggers; exercises only run when the user presses r.

Sources: src/cli.rs8-29

Subcommands

The Command enum defines the primary actions available to the user.

Sources: src/cli.rs31-57

For a deep dive into every command and its specific arguments, see CLI Commands and Arguments.

Execution Flow

The main function in src/main.rs serves as the central dispatcher. It parses arguments and determines if a "priority command" (like init or dev) should run before the full application state is initialized.

Initialization Logic

Before most commands can run, Rustlings performs several checks:

1. Repository Check: Verifies the user isn't trying to run the tool from a cloned repository (the "old method") by checking for dev/rustlings-repo.txt. src/main.rs39-41
2. Directory Validation: Ensures the exercises/ directory exists in the current working directory. src/main.rs53-56
3. Metadata Parsing: Parses info.toml via InfoFile::parse(). src/main.rs58
4. State Restoration: Initializes AppState, which loads progress from .rustlings-state.txt. src/main.rs71-76

Command Dispatch Diagram

This diagram maps the high-level logic in main to the internal modules and functions responsible for execution.

Sources: src/main.rs36-187

Interactive Modes

If no subcommand is provided, Rustlings defaults to Watch Mode via watch::watch. src/main.rs101-123

• Watch Mode: The primary loop where users solve exercises. It monitors file changes and handles terminal input.
• Manual Run: If --manual-run is passed, the notify_exercise_names passed to watch is None, disabling automatic triggers. src/main.rs106-119

For more details on the interactive UI components, see Watch Mode and List Mode.

Editor Integration

Rustlings can automatically open the current exercise in an editor. This behavior is managed by the Editor enum and triggered during the AppState initialization.

• VS Code/Codium: Detected via the TERM_PROGRAM environment variable. src/main.rs64 It checks for the existence of code or codium binaries. src/editor.rs50-55
• Zellij: Supported if the ZELLIJ environment variable is present and the zellij binary is found. src/editor.rs67-69
• Custom: Configured via the --edit-cmd flag. src/editor.rs57-65

The application uses EditorJoinHandle to spawn editor processes in a separate thread, ensuring the CLI remains responsive. src/editor.rs79-114

For details on how specific editors are handled and the non-blocking spawn logic, see Editor Integration.

Core Components for CLI

The CLI interacts with several key architectural components:

• AppState: Manages the current exercise index, persistence via .rustlings-state.txt, and exercise completion status. src/app_state.rs52-65
• CmdRunner: Built during AppState creation, it handles cargo execution (build, test, clippy) and captures output. src/app_state.rs74 src/exercise.rs108-157
• RunnableExercise: A trait implemented for Exercise that defines the logic for run_exercise and run_solution. src/exercise.rs96-200

Sources: src/app_state.rs52-83 src/exercise.rs96-167 src/main.rs71-76