sc-020.md

← Back to Backlog

[SC-020] Import and export WSL distributions to/from files

Status: Open Priority: Medium Component: tools/wsl-manager/wsl-manager.ps1, lib/wsl/ops.ps1, lib/wsl/commands.ps1

Summary: As a WSL manager user, I want to export a distribution to a tar file and import a distribution from a tar file so that I can create backups, share environments with colleagues, and reuse pre-configured distributions across machines.

Description: The existing clone command already uses wsl.exe --export and wsl.exe --import internally but treats the tar file as a transient artefact that is deleted after the clone completes. This item adds two new top-level commands - export and import - that let the user choose the file path explicitly.

Use cases

• Backup: export a distro before a risky operation, re-import if something goes wrong
• Sharing: export a fully configured distro, share the tar file with a team member who imports it
• Reuse: maintain a library of golden images (e.g. dev-base.tar) and import on demand

Proposed commands

wsl-manager export <DistroName> [<FilePath>]
wsl-manager import <DistroName> <FilePath> [<InstallPath>]

export

Parameter	Required	Description
DistroName	yes (prompt if missing)	Name of the distribution to export
FilePath	no	Destination tar file. Default: $HOME\wsl-exports\<DistroName>_<timestamp>.tar

• The source distribution must be stopped before export (same guard as clone)
• If the target file already exists, prompt for overwrite confirmation
• Print the resulting file path and size on success

import

Parameter	Required	Description
DistroName	yes (prompt if missing)	Name for the imported distribution (must not already exist)
FilePath	yes (prompt if missing)	Path to the tar file to import
InstallPath	no	Where to store the imported distro's vhdx. Default: same logic as clone ($env:LOCALAPPDATA\wsl\<DistroName> or $env:WSL_INSTALL_PATH\<DistroName>)

• Validate that the tar file exists before calling wsl.exe --import
• Reject if a distribution with the same name already exists
• Set the imported distro to WSL 2 (wsl.exe --set-version <name> 2) if it isn't already

Scope decisions

• Reuse the existing termination guard from clone (Stop-WslDistro / running-state check)
• Reuse the $env:WSL_INSTALL_PATH / default-path logic already in Invoke-CloneDistro
• Add export and import to ValidateSet, Invoke-WslCommand dispatcher, and interactive menu
• Menu keys: E for export, I for import (verify no conflict with existing keys)
• File format is always .tar (the native wsl.exe --export format)
• No compression (gzip/zstd) in initial scope; can be added later as an enhancement
• No progress bar in initial scope; wsl.exe does not expose progress, so this would require polling file size

Technical notes

• Invoke-ExportDistro and Invoke-ImportDistro should be added to ops.ps1 alongside Invoke-CloneDistro, following the same pattern
• Register both commands in Invoke-WslCommand dispatcher in commands.ps1
• Add menu entries in Start-InteractiveMode in manager.ps1
• Update the .SYNOPSIS / .DESCRIPTION help text in wsl-manager.ps1
• Update ValidateSet for $Command parameter

Acceptance Criteria:

• wsl-manager export <name> exports the named distro to a tar file and prints the path
• wsl-manager export <name> <path> exports to the specified file
• wsl-manager import <name> <path> imports a tar file as a new distribution
• wsl-manager import <name> <path> <installPath> respects custom install path
• Export prompts for distro name when not provided (interactive selection)
• Import prompts for distro name and file path when not provided
• Export refuses to overwrite an existing file without confirmation
• Import rejects if a distribution with the given name already exists
• Source distribution is terminated before export if running
• Interactive menu includes both new commands
• Unit tests cover success, failure, and edge cases for both commands
• All existing tests continue to pass

← Back to Backlog