wslshot 0.1.1

Copy Windows screenshots into WSL for easy reuse.

Windows Screenshot for Linux

wslshot is a CLI tool designed to fetch the latest screenshot(s) from a directory shared with a Windows host, copy them to a designated directory in a Linux VM, and output their new paths in a configurable style (Markdown, HTML, or text).

Take a screenshot using the Windows Snipping tool (win + shift + S), then run wslshot in your terminal to transfer the image.

Table of Contents

1. Features
2. AI Agent Snippet
3. Installation
   1. Install with pip
   2. Install with uv
4. Quick Start
5. Windows Configuration
   1. For Windows 11 Users
   2. For Windows 10 Users
6. Shared Directory Configuration
   1. For WSL Users
   2. For Virtual Machine Users
7. Configuration
8. Fetching Screenshots
9. Using a Specific Image Path
   1. Output
   2. File Copy Behavior
10. Vim Integration

Features

• Set a default source directory for screenshots.
• Designate a custom source or destination directory per operation, or let wslshot detect typical image directories automatically.
• Fetch the most recent screenshot or specify a number of recent screenshots to fetch.
• Print source paths without copying files using --no-transfer.
• Control automatic staging of screenshots when copied to a git repository.
• Convert screenshots to png, jpg/jpeg, webp, or gif during copy (flag or default).
• Optimize copied screenshots in place without changing filenames or extensions.
• Set a default output style (Markdown, HTML, text) and specify a custom style per operation.
• Migrate legacy config values with migrate-config --dry-run.

AI Agent Snippet

Nice thing to have in your AGENTS.md:

## Screenshots ("use/look at a screenshot")
* Run `wslshot -n <number> --no-transfer` to pick n screenshots.
* Run `wslshot --optimize` to copy the latest screenshot and optimize it when preparing docs/images.

Example

Look at my last screenshot.

The agent will run wslshot -n 1 --no-transfer and inspect it.

Installation

Ensure you have Python 3.10 or later installed on your system.

Install with pip

python3 -m pip install wslshot

Install with uv

uv tool install wslshot

Quick Start

This assumes your Windows screenshots are already saved in a directory your Linux environment can access.

wslshot configure --source /path --destination /path
wslshot

Windows Configuration

Before using wslshot, you need to ensure that your screenshots are automatically saved to a directory accessible by your Linux environment.

For Windows 11 Users

The Windows Snipping Tool in Windows 11 supports automatic saving of screenshots (it should be enabled by default):

1. Open the Snipping Tool.
2. Click on "Settings...".
3. Toggle the box that says "Automatically save screenshots".

For Windows 10 Users

The Snipping Tool in Windows 10 doesn't support automatic saving. However, you can use the following methods to automatically save screenshots:

1. Use Win + PrtScn: It captures the entire screen and saves to C:\Users\[Your Username]\Pictures\Screenshots.
2. Use Win + Alt + PrtScn: It captures the active window and saves to C:\Users\[Your Username]\Videos\Captures.
   • To unify the save directory, right-click on the Captures directory, select Properties, and set your desired directory in the Location tab.
3. Use a third-party tool.

You can still use the Snipping Tool, but you'll need to manually save each screenshot after capturing it.

Shared Directory Configuration

For wslshot to fetch screenshots from your Windows host, you need to set up a shared directory between your Windows host and your Linux VM.

For WSL Users

If you are using the Windows Subsystem for Linux (WSL), you can directly access your Windows file system from your WSL distro. The Windows C: drive, for example, can be found at /mnt/c/ within your WSL environment. Therefore, you can directly use a directory on your Windows file system as the source directory for wslshot.

For Virtual Machine Users

If you are using a traditional virtual machine managed by a hypervisor (e.g., VirtualBox, VMware, Hyper-V), you'll need to set up a shared directory with your Windows host and the Linux VM. The process varies depending on your hypervisor, but here are general steps:

1. Choose a directory on your Windows host to use as your screenshot directory. This should be the same directory where you configured your Snipping Tool to automatically save screenshots.
2. Go into your VM settings and locate the shared directories option. Add the chosen screenshot directory as a shared directory.
3. Depending on your VM settings, this directory will now be available at a certain path in your Linux environment. Use this path as your source directory for wslshot.

Remember to consult the documentation of your hypervisor for specific instructions on how to set up shared directories.

Configuration

Configure wslshot to suit your needs using the configure command:

wslshot configure [--source /path] [--destination /path] [--auto-stage-enabled True] [--output-style HTML] [--convert-to png]

This command allows you to set various options:

• --source or -s: This option lets you specify the default source directory where wslshot will look for screenshots.

• --destination or -d: This option lets you specify the default destination directory where wslshot will copy screenshots. When running inside a git repository, this default is ignored unless you pass --destination on that command; otherwise, wslshot uses repository image directories (/img/, /images/, /assets/img/, /assets/images/) in that order.

• --auto-stage-enabled: This option lets you control whether screenshots are automatically staged when copied to a git repository. By default, this option is set to False. If this option is set to True, any screenshot copied to a git repository will automatically be staged for commit.

• --output-style: This option lets you set the default output style for the links to the screenshots that wslshot creates. The available styles are Markdown, HTML, and text. If you do not set this option, wslshot will output links in Markdown format by default.

• --convert-to or -c: Set the default image conversion format. Supported formats: png, jpg, jpeg, webp, gif. Conversion runs after copying; the converted file replaces the copied original. jpeg is treated as jpg. A CLI --convert-to flag overrides this default.

These are default settings. Override them on a per-operation basis by providing the corresponding options when running the wslshot command.

Migrate older configuration keys to the current names with migrate-config:

wslshot migrate-config --dry-run
wslshot migrate-config

Use --dry-run to preview changes without writing the config file.

Fetching Screenshots

Fetch screenshots with the wslshot command:

wslshot

This fetches the most recent screenshot from the source directory. If run inside a git repository, wslshot looks for an existing image directory (checked in priority order) and copies the screenshot there. If none exists, it creates /assets/images/.

Directories checked in priority order:

1. /img/
2. /images/
3. /assets/img/
4. /assets/images/

You can also choose a specific number of screenshots:

wslshot -n 3

This fetches the three most recent screenshots.

Print source paths without copying files:

wslshot --no-transfer

This prints the source paths for the selected screenshots without copying files or interacting with git. Output defaults to text; override with --output-style.

This mode rejects flags that require transfer (--destination, --convert-to, --optimize).

Convert screenshots to a different format:

wslshot --convert-to png

This converts the screenshot(s) to the specified format. Supported formats: png, jpg, jpeg, webp, gif. If a default conversion is set in configuration, it runs when no flag is provided. Conversion happens after copying, and the converted file replaces the copied original. If auto-staging is enabled in a git repository, only the converted file is staged. Conversion is skipped only when the copied file already has the target extension; .jpeg files are rewritten to .jpg. Conversion applies both to the latest-screenshot workflow and when you pass a specific image path.

Optimize copied screenshots in place:

wslshot --optimize

This optimizes copied screenshots after transfer and rewrites destination files in place. Source files are never modified. Optimization preserves each copied file's extension. If a default conversion format is configured, --optimize takes precedence for that run and skips conversion.

--optimize conflicts with --no-transfer and --convert-to.

Allow symlinks (security risk):

wslshot --allow-symlinks

WARNING: Only use with trusted paths. By default, wslshot rejects symlinks for security.

These are all the possible options:

wslshot [--source /custom/source] [--destination /custom/destination] [--count 3] [--output-style HTML] [--no-transfer] [--convert-to png] [--optimize] [--allow-symlinks]

Notes:

• --no-transfer cannot be combined with --destination, --convert-to, or --optimize.
• --optimize cannot be combined with --convert-to.

Using a Specific Image Path

Provide the path to a specific image as an argument:

wslshot /mnt/c/user/my_name/Images/magic.gif

Note that you can drag and drop a file into the Windows Terminal to automatically populate its path.

Output

Upon success, the command outputs the new path in your configured output style (Markdown by default). Override per run with --output-style:

![<uuid>.gif](/assets/images/<uuid>.gif)

File Copy Behavior

The specified image is copied to your designated directory on the Linux VM.

Supported source image formats are PNG, JPEG/JPG, and GIF.

Vim Integration

If wslshot is in your PATH, call it with a filter command:

:.!wslshot

---

https://github.com/sderev/wslshot