{"id":18613552,"url":"https://github.com/kim-hwiwon/WslCmd","last_synced_at":"2025-04-10T23:32:04.678Z","repository":{"id":114674348,"uuid":"299472460","full_name":"kim-hwiwon/WslCmd","owner":"kim-hwiwon","description":"A simple executable binary for running commands/programs of WSL at Windows side (cmd, powershell, icon-click, etc.)","archived":false,"fork":false,"pushed_at":"2022-06-07T02:17:46.000Z","size":81,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-18T03:43:00.918Z","etag":null,"topics":["gui","linux","shell","windows","wsl"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kim-hwiwon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-29T01:25:19.000Z","updated_at":"2021-10-15T10:00:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"bfe2122e-15e2-4536-80ca-e7b47322b186","html_url":"https://github.com/kim-hwiwon/WslCmd","commit_stats":null,"previous_names":["hwiwon-kim/wslcmd","kim-hwiwon/wslcmd"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kim-hwiwon%2FWslCmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kim-hwiwon%2FWslCmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kim-hwiwon%2FWslCmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kim-hwiwon%2FWslCmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kim-hwiwon","download_url":"https://codeload.github.com/kim-hwiwon/WslCmd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248316431,"owners_count":21083443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gui","linux","shell","windows","wsl"],"created_at":"2024-11-07T03:22:43.242Z","updated_at":"2025-04-10T23:32:04.666Z","avatar_url":"https://github.com/kim-hwiwon.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WslCmd\n- A simple executable binary for running commands/programs of WSL at Windows side (cmd, powershell, icon-click, etc.)\n- Author: snoopy3476@outlook.com\n\n\n## Description\n\n\n### About\n- Create and manage symlinks to commands of WSL (inside the directory where the executable binary exists)\n- When running WSL commands on Windows shell, converts Windows path arguments to WSL path if exists.\n\n  See [Path argument auto-conversion part](#path-argument-auto-conversion-and-backslash-escaping) for more details.\n\n\n\n### Brief usage examples\n\n- Use WSL commands directly on Windows command prompt\n```\nC:\\\u003ewslcmd list\n(No linked WSL command)\n \nC:\\\u003egit --version \u0026 ls C:\\Users\n'git' is not recognized as an internal or external command,\noperable program or batch file.\n'ls' is not recognized as an internal or external command,\noperable program or batch file.\n\nC:\\\u003ewslcmd add git ls\n - Linked command(s) successfully\n\nC:\\\u003ewslcmd list\ngit     ls\n\nC:\\\u003egit --version \u0026 ls C:\\Users\ngit version 2.25.1\n'All Users'   Default  'Default User'   Public   desktop.ini   snoop\n\nC:\\\u003e\n```\n\n- Set a WSL program as a default program for some file-extensions\n  - When clicking a file with those file-extensions on Windows explorer, the file can be open with the WSL program directly\n  - See [Detached process mode (GUI program mode) part](#detached-process-mode-gui-program-mode) for more information\n\n\n## Prerequisites\n- [WSL Installed](https://docs.microsoft.com/en-us/windows/wsl/install)\n- Windows 'Developer Mode' enabled, for creating symlink in Windows\n  - This is optional, but [creating new commands in the command management](#executable-basic-usage) below should be run as administrator if not in dev mode\n\n\n## Build \u0026 Install\n\nFirst, you can select one of below to install:\n\n- Download a pre-compiled executable binary from [Releases](https://github.com/snoopy3476/WslCmd/releases).\n  1. Make folder for WslCmd\n  \n     (CMD/PowerShell) `cmd /C \"mkdir %USERPROFILE%\\WslCmd\\bin\"`\n     \n  2. Put the downloaded binary into the created folder\n  \n     (CMD/PowerShell) `cmd /C \"copy path\\to\\wslcmd.exe %USERPROFILE%\\WslCmd\\bin\"`\n\n- Build on Windows native (may need to install Visual Studio)\n  1. [Install Rust for Windows](https://www.rust-lang.org/tools/install)\n  2. Build and install with Cargo in Windows CMD:\n  \n     (CMD/PowerShell) ```cmd /C \"cargo install --git=https://github.com/snoopy3476/WslCmd.git --root=%USERPROFILE%\\WslCmd\"```\n     \n     Executable will be placed in 'bin' folder inside the specified root.\n    \n- Build on WSL (no need to install Visual Studio, but mingw-64 is needed)\n  1. [Install Rust for WSL](https://www.rust-lang.org/tools/install)\n  2. Install prerequisites on WSL\n     - Install mingw-64\n\n       (Debian/Ubuntu Shell Example) ```sudo apt install mingw-w64```\n       \n     - Install rustup target for cross-compile\n     \n       (WSL Shell) ```rustup target add x86_64-pc-windows-gnu```\n       \n  3. Build on WSL \u0026 install to Windows with Cargo:\n  \n     (WSL Shell)\n     ```\n     # Get %USERPROFILE% env var from Windows\n     WSLCMD_ROOT=$(\n         wslpath $(cmd.exe /Q /C \"echo %USERPROFILE%\\\\WslCmd\" \\\n                   2\u003e/dev/null | tr -d '\\r' | tr -d '\\n' )) \u0026\u0026\n\n     # If getting $WSLCMD_ROOT is successful, cargo install to there\n     test -n \"$WSLCMD_ROOT\" \u0026\u0026\n     cargo install --git=https://github.com/snoopy3476/WslCmd.git \\\n                   --target=x86_64-pc-windows-gnu \\\n                   --root=\"$WSLCMD_ROOT\"\n     \n     # When failed to install because of abnormal $WSLCMD_ROOT,\n     # run only 'cargo install ...' with setting '--root=' manually\n     ```\n\n     Executable will be placed in 'bin' directory inside the specified root.\n\n\nThen, append the folder path (where the executable exists) to Windows 'PATH' environment variables:\n   1. Append installed path to Windows PATH env var\n      1. Go to System Properties\n         1. Press `[Windows key] + [R]` keys\n         2. Enter `SystemPropertiesAdvanced`\n         3. Press `[Enter]` key\n      2. Click 'Environment Variables'\n      3. Double click 'Path' at **'User Environment Variable'** region, then add WslCmd binary folder path into it\n         - *Ex)* `%USERPROFILE%\\WslCmd\\bin`\n   2. Re-open CMD to apply modified PATH\n      - If you are using Windows Terminal, you need to close and re-open Windows Terminal itself.\n\n\n## Uninstall\n1. Remove WslCmd root folder\n2. Remove WslCmd bin folder from Windows PATH env vars\n   1. Go to System Properties\n      1. Press `[Windows key] + [R]` keys\n      2. Enter `SystemPropertiesAdvanced`\n      3. Press `[Enter]` key\n   2. Click 'Environment Variables'\n   3. Double click 'Path' at user environment variable region, find the WslCmd path, and remove it\n      - *Ex)* `%USERPROFILE%\\WslCmd\\bin`\n\n\n## Usage\n### Executable basic usage\n- Command management\n  - Link new commands:\n    ```\n    wslcmd add \u003ccommand-1\u003e (\u003ccommand-2\u003e) ...\n           a        \"            \"       ...\n           new      \"            \"       ...\n           n        \"            \"       ...\n    ```\n  - Unlink existing commands:\n    ```\n    wslcmd del \u003ccommand-1\u003e (\u003ccommand-2\u003e) ...\n           d        \"            \"       ...\n           rm       \"            \"       ...\n           r        \"            \"       ...\n    ```\n  - List linked commands:\n    ```\n    wslcmd list\n           ls\n           l\n    ```\n- Command execution\n  - `\u003ccommand-name\u003e \u003ccommand-arg1\u003e \u003ccommand-arg2\u003e ...`\n  - *Ex)*\n    - `emacs ~/src/project1/project1.sh`           *(Using WSL path as arguments)*\n    - `emacs C:\\Users\\(user-home)\\bin\\test.txt`    *(Using absolute Windows path as arguments)*\n    - `emacs bin\\test.txt`                         *(Using relative Windows path as arguments)*\n\n\n### Detached process mode (GUI program mode)\n\n- Note that 'Linux GUI server for Windows' (WSLg, VcXsrv, etc.) is required for running GUI programs!\n- When creating a command, additional command with a leading period \\(`.`\\) is also created internally\n\n- Running a command starting with a `.` will run the command as a detached, backgroud process\n  - Detached background process here does not tied to the running shell, so you can close the shell after running it\n  - This is useful when you want to execute GUI program of WSL\n  - *Ex)*\n    - `wslcmd new emacs`        *(Create new links to WSL command 'emacs')*\n    - `.emacs bin\\test.txt`      *(run 'emacs' at background, and detach)*\n\n- Usage examples\n\n  - **Open specific file-extensions with WSL GUI programs by default**\n    - Set a WSL GUI program symlink (`.(command-name).exe`, executable with a leading period) as a default program ('Open with...') for some file-extensions\n      - After doing this, the WSL program can open a file with those extensions directly, if you double-click the file icon at Windows file explorer\n\n  - **Add WSL GUI programs to Windows start menu as Windows program**\n    - Make a shortcut link (.lnk) to the command file `(command-name).exe` (**No leading period here**) or run it directly, to run GUI programs with mouse click\n      1. Go to the folder where the WslCmd binary exists\n      2. Create a shortcut to `(command-name).exe` file manually with mouse right click\n          - Change the shortcut file name which is displayed as program name\n          - Set a icon of the link file which is displayed as program icon\n          - Set additional binary arguments for the link file if you want\n      3. Open the 'Windows start menu' folder\n          - Press `[Windows key] + [R]` keys\n          - Enter `shell:Start Menu`\n          - Press `[Enter]` key\n      4. Move the created shortcut in step 2 to the start menu folder\n      5. Search and pin the WSL GUI program to Windows start menu\n          - Press `[Windows key]` key to open the start menu\n          - Enter the name of the link file you made when the start menu is appeared\n          - Mouse right click at the searched program, then pin to start menu\n\n\n### Command name format\nBy formatting command name when creating and executing a command, running WSL commands as different WSL user or distribution is also possible.\n\nFormatting is done by the delimiter `!` (which has no problem to be executed as a command-name on cmd, powershell, and bash). Empty field will be set to default. Detailed full-format of the command name is as follows:\n- `\u003ccommand-name\u003e!\u003cuser-name\u003e!\u003cdist-name\u003e`\n  - *Ex) Running command as...*\n    - Default user \u0026 Default dist: `command`\n    - User 'john' \u0026 Default dist: `command!john`\n    - Default user \u0026 Dist 'Ubuntu': `command!!ubuntu`\n    - User 'john' \u0026 Disk 'Debian': `command!john!debian`\n- Usage *Ex)*\n  ```\n  C:\\\u003ewslcmd l\n  (No linked WSL command)\n\n  C:\\\u003ewslcmd a lsb_release!!ubuntu lsb_release!!debian\n   - Linked command(s) successfully\n\n  C:\\\u003ewslcmd l\n  lsb_release!!debian     lsb_release!!ubuntu\n\n  C:\\\u003elsb_release!!debian -d\n  Description:    Debian GNU/Linux 11 (bullseye)\n\n  C:\\\u003elsb_release!!ubuntu -d\n  Description:    Ubuntu 20.04.3 LTS\n  \n  C:\\\u003e\n  \n  ```\n\n\n### Path argument auto-conversion and Backslash escaping\nWslCmd tries to convert Windows path arguments to WSL-understandable path. This is necessary because most Windows programs (including explorer.exe, etc.) pass path argument(s) as `\\`-separated version, instead of `/` one. This function is disabled when the environment variable `WSLCMD_NO_ARGCONV` is set.\n\n- Conversion of Windows absolute path to WSL path\n  - Wraps `[a-zA-Z]:[\\/]` patterned argument (after unquoted) with wslpath substitution\n    - *Ex)*\n      - *Input*: `printf \"C:\\tmp\\example-file.txt\"`\n      - *Output*: `/mnt/c/tmp/example-file.txt`\n  - Does not work if a Windows path is embedded inside other strings\n    - *Ex)*\n      - *Input*: `printf \"Test=C:\\tmp\\example-file.txt\"`\n      - *Output*: `Test=C:/tmp/example-file.txt`\n\n- Conversion of Windows relative path to WSL path\n  - Unlike absolute path, as there is no reliable way to check whether the argument is relative or not, WslCmd first converts all single `\\` to `/` to cover almost all of relative path patterns.\n  \n    Then, to represent single or consecutive `\\`(s), you can escape it with another leading `\\`. Detailed rules are as follows:\n    - Rules\n      - (Single `\\`) -\u003e `/`\n        - This is for passing relative path to WSL binaries\n      - (Consecutive `\\`s) -\u003e (Remaining `\\`(s) without the first `\\` character)\n        - *Ex)*\n          - `\\\\` -\u003e `\\`\n          - `\\\\\\` -\u003e `\\\\`\n          - ...\n    - *Ex)*\n      - *Input*: `printf \\example\\\\\\strin\\\\g:\\\\ \\\\'[%s]\\\\' \"ARG-INPUT\"`\n      - *(After conversion is done before run)*: `printf /example\\\\strin\\g:\\ \\'[%s]\\' \"ARG-INPUT\"` (\u003c- actual input on WSL shell)\n      - *Output*: `/example\\string: '[ARG-INPUT]'`\n      \n  - Of course, special characters of cmd/powershell themselves should be also escaped\n\n\n### Environments\nFollowing environment files are loaded before execution if exists:\n- `/etc/profile`\n- `$HOME/.profile`\n- `(wslcmd-exe-dir)\\profile` (File `profile` inside the wslcmd exe folder)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkim-hwiwon%2FWslCmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkim-hwiwon%2FWslCmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkim-hwiwon%2FWslCmd/lists"}