Dry-Run Mode
Relevant source files
The following files were used as context for generating this wiki page:
Dry-Run Mode is a diagnostic and safety feature in vscli that allows users to simulate the process of detecting and preparing a workspace or dev container without actually executing the external editor command (e.g., code, cursor). It is designed to verify configuration logic, dev container detection, and URI generation before any external processes are spawned.
When enabled, the application performs all internal operations—such as parsing command-line options, loading history, searching for dev container configurations, and calculating the final command-line arguments—but bypasses the final system call that would launch the editor. This mode is particularly useful for debugging complex dev container setups or verifying path conversions in environment-specific scenarios like WSL.
Sources: src/opts.rs:20-22, src/workspace.rs:288-293, README.md:92-93
Configuration and Activation
Dry-Run Mode is controlled via a global configuration flag. It can be activated through command-line arguments or environment variables.
| Option | Shorthand | Environment Variable | Description |
|---|---|---|---|
--dry-run | -d | DRY_RUN | Whether to launch in dry-run mode (not actually open vscode). |
Sources: src/opts.rs:20-22, README.md:92-93
The flag is defined as a global argument in the Opts struct, meaning it is available to all subcommands, including open and recent.
Sources: src/opts.rs:11-28
System Architecture and Data Flow
The dry_run state is captured at the entry point of the application and propagated through the system's setup and execution layers.
Data Propagation Flow
The following diagram illustrates how the dry_run boolean is passed from the command-line parser to the final execution logic.
In src/main.rs, the opts.dry_run value is extracted and passed into the Setup struct during the execution of both open and recent commands.
Sources: src/main.rs:65, src/main.rs:104
Implementation in the Launch Sequence
The Setup struct in src/launch.rs maintains the dry_run state. When Setup::launch is called, it determines the appropriate workspace opening method (classic or dev container) and passes the dry_run flag down to the Workspace methods.
pub fn launch(self, config: Option<PathBuf>) -> Result<Option<DevContainer>> {
// ... logic to determine dev_container ...
self.workspace.open(
self.behavior.args,
self.dry_run, // Flag passed here
dev_container,
&self.behavior.command,
)?;
// ...
}
Sources: src/launch.rs:118-123, src/launch.rs:130-134
Execution Shielding
The final stage of the Dry-Run Mode logic resides in the run function within src/workspace.rs. This function acts as the gatekeeper for system commands.
Logic Gate
The run function receives the command string, the constructed arguments, and the dry_run boolean. It logs the "executable" and "final args" at the DEBUG level regardless of the mode, but wraps the actual Command::new().output() call in a conditional check.
fn run(cmd: &str, args: Vec<OsString>, dry_run: bool) -> Result<()> {
debug!("executable: {cmd}");
debug!("final args: {args:?}");
if !dry_run {
let output = Command::new(cmd).args(args).output()?;
debug!("Command output: {output:?}");
}
Ok(())
}
Sources: src/workspace.rs:288-298
Comparison of Execution Modes
| Aspect | Standard Mode | Dry-Run Mode |
|---|---|---|
| Workspace Detection | Performed | Performed |
| Path Canonicalization | Performed | Performed |
| URI Generation | Performed | Performed |
| History Update | History is updated | History is updated |
| Logging | Executable and args logged | Executable and args logged |
| Process Spawning | Editor process is started | No process is started |
Sources: src/main.rs:72-81, src/workspace.rs:291-297
Interaction with History Tracker
It is important to note that Dry-Run Mode does not prevent the application from updating the history file. In src/main.rs, after the setup.launch call (which honors the dry-run flag), the application proceeds to update the Tracker with the workspace and dev container information.
Sources: src/main.rs:65-81, src/workspace.rs:288-298
Conclusion
Dry-Run Mode provides a non-destructive way to inspect the internal logic of vscli. By following the data flow from Opts through Setup to the gated run function, the system ensures that all complex logic—including dev container detection in src/workspace.rs and launch strategy resolution in src/launch.rs—is fully exercised while preventing the actual launch of the external editor.