{"id":13626107,"url":"https://github.com/michidk/vscli","last_synced_at":"2025-05-15T02:09:47.335Z","repository":{"id":111672558,"uuid":"609615063","full_name":"michidk/vscli","owner":"michidk","description":"A CLI/TUI that simplifies launching VSCode projects, with a focus on dev containers","archived":false,"fork":false,"pushed_at":"2025-04-05T18:12:09.000Z","size":725,"stargazers_count":396,"open_issues_count":6,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-13T13:38:40.140Z","etag":null,"topics":["cli","command-line","devcontainer","hacktoberfest","rust","terminal","vscode"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/vscli","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/michidk.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,"zenodo":null}},"created_at":"2023-03-04T18:00:48.000Z","updated_at":"2025-04-10T23:19:51.000Z","dependencies_parsed_at":"2024-05-08T01:31:25.931Z","dependency_job_id":"5bc06314-09bc-46ac-bcbc-493cc042684e","html_url":"https://github.com/michidk/vscli","commit_stats":{"total_commits":17,"total_committers":1,"mean_commits":17.0,"dds":0.0,"last_synced_commit":"a26f7e84ae24897d6bda5ab9945ab672a2a60e42"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michidk%2Fvscli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michidk%2Fvscli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michidk%2Fvscli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michidk%2Fvscli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michidk","download_url":"https://codeload.github.com/michidk/vscli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254259384,"owners_count":22040820,"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":["cli","command-line","devcontainer","hacktoberfest","rust","terminal","vscode"],"created_at":"2024-08-01T21:02:10.215Z","updated_at":"2025-05-15T02:09:47.290Z","avatar_url":"https://github.com/michidk.png","language":"Rust","readme":"# vscli\n\n[![MIT License](https://img.shields.io/crates/l/vscli)](https://choosealicense.com/licenses/mit/) [![Continuous integration](https://github.com/michidk/vscli/actions/workflows/ci.yml/badge.svg)](https://github.com/michidk/vscli/actions/workflows/ci.yml)\n\nA CLI/TUI which makes it easy to launch [Visual Studio Code](https://code.visualstudio.com/) (vscode) [dev containers](https://containers.dev/). Also supports other editors like [Cursor](https://www.cursor.com/).\n\n![Screenshot showing the recent UI feature.](.github/images/recent.png)\n\nRead [here](https://blog.lohr.dev/launching-dev-containers) about the journey of reverse engineering Microsoft's dev container CLI in order to make this.\n\n## Features\n\n- A shorthand for launching vscode projects (to be used like the `code` command but with dev container support)\n- Supports different editors like `vscode`, `vscode-insiders`, `cursor` and other vscode forks\n- Detects whether a project is a [dev container](https://containers.dev/) project, and launches the dev container instead\n- Supports [multiple dev containers](https://github.com/microsoft/vscode-docs/blob/main/remote-release-notes/v1_75.md#folders-with-multiple-devcontainerjson-files) in the same project\n- Tracks your projects and allows you to open them using a CLI-based UI\n\n## Installation\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/vscli.svg)](https://repology.org/project/vscli/versions)\n\n[![Homebrew](https://img.shields.io/badge/homebrew-available-blue?style=flat)](https://github.com/michidk/homebrew-tools/blob/main/Formula/vscli.rb)\n\n### [Cargo](https://doc.rust-lang.org/cargo/)\n\nInstall [vscli using cargo](https://crates.io/crates/vscli) on Windows or Linux:\n\n```sh\ncargo install vscli\n```\n\n### [Homebrew](https://brew.sh/)\n\nInstall [vscli using homebrew](https://github.com/michidk/homebrew-tools/blob/main/Formula/vscli.rb) on Linux or Mac:\n\n```sh\nbrew install michidk/tools/vscli\n```\n\n### [Chocolatey](https://chocolatey.org/)\n\nInstall [vscli using Chocolatey](https://community.chocolatey.org/packages/vscli) on Windows:\n\n```sh\nchoco install vscli\n```\n\n### [Winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/)\n\nInstall [vscli using winget](https://github.com/microsoft/winget-pkgs/tree/master/manifests/m/michidk/vscli) on Windows:\n\n```sh\nwinget install vscli\n```\n\n### Additional steps\n\nYou can set a shorthand alias for `vscli` in your shell's configuration file:\n\n```sh\nalias vs=\"vscli open\"\nalias vsr=\"vscli recent\"\n```\n\n## Usage\n\n### Commands\n\nAfter installation, the `vscli` command will be available:\n\n```\nUsage: vscli [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  open    Opens a dev container\n  recent  Opens an interactive list of recently used workspaces\n  help    Print this message or the help of the given subcommand(s)\n\nOptions:\n  -s, --history-path \u003cHISTORY_PATH\u003e  Overwrite the default path to the history file [env: HISTORY_PATH=]\n  -d, --dry-run                      Whether to launch in dry-run mode (not actually open vscode) [env: DRY_RUN=]\n  -v, --verbose...                   Increase logging verbosity\n  -q, --quiet...                     Decrease logging verbosity\n  -h, --help                         Print help\n  -V, --version                      Print version\n```\n\n#### Open Dev Containers\n\nOpens a dev container.\n\n```\nUsage: vscli open [OPTIONS] [PATH] [ARGS]...\n\nArguments:\n  [PATH]     The path of the vscode project to open [default: .]\n  [ARGS]...  Additional arguments to pass to the editor [env: ARGS=]\n\nOptions:\n  -c, --command \u003cCOMMAND\u003e            The editor command to use (e.g. \"code\", \"code-insiders\", \"cursor\") [env: COMMAND=]\n  -s, --history-path \u003cHISTORY_PATH\u003e  Overwrite the default path to the history file [env: HISTORY_PATH=]\n  -b, --behavior \u003cBEHAVIOR\u003e          Launch behavior [possible values: detect, force-container, force-classic]\n  -d, --dry-run                      Whether to launch in dry-run mode (not actually open vscode) [env: DRY_RUN=]\n      --config \u003cCONFIG\u003e              Overwrites the path to the dev container config file [env: CONFIG=]\n  -v, --verbose...                   Increase logging verbosity\n  -q, --quiet...                     Decrease logging verbosity\n  -h, --help                         Print help (see more with '--help')\n```\n\n#### Recent UI\n\nOpens an interactive list of recently used workspaces.\n\n```\nUsage: vscli recent [OPTIONS] [ARGS]...\n\nArguments:\n  [ARGS]...  Additional arguments to pass to the editor [env: ARGS=]\n\nOptions:\n      --hide-instructions            Hide the instruction message in the UI\n  -s, --history-path \u003cHISTORY_PATH\u003e  Overwrite the default path to the history file [env: HISTORY_PATH=]\n  -d, --dry-run                      Whether to launch in dry-run mode (not actually open vscode) [env: DRY_RUN=]\n      --hide-info                    Hide additional information like strategy, command, args and dev container path in the UI\n  -c, --command \u003cCOMMAND\u003e            The editor command to use (e.g. \"code\", \"code-insiders\", \"cursor\") [env: COMMAND=]\n  -v, --verbose...                   Increase logging verbosity\n  -b, --behavior \u003cBEHAVIOR\u003e          Launch behavior [possible values: detect, force-container, force-classic]\n  -q, --quiet...                     Decrease logging verbosity\n      --config \u003cCONFIG\u003e              Overwrites the path to the dev container config file [env: CONFIG=]\n  -h, --help                         Print help (see more with '--help')\n```\n\nBoth the `open` and `recent` commands share the same set of launch arguments:\n\n- `--command`: Specify which editor command to use (e.g., \"code\", \"code-insiders\", \"cursor\")\n- `--behavior`: Set the launch behavior (\"detect\", \"force-container\", \"force-classic\")\n- `--config`: Override the path to the dev container config file\n- Additional arguments can be passed to the editor executable by specifying them after `--`\n\nThe `recent` command additionally supports:\n- `--hide-instructions`: Hide the keybinding instructions from the UI\n- `--hide-info`: Hide additional information like strategy, command, args and dev container path\n\n##### Keybindings\n\n| Key/Key Combination             | Action                | Description                            |\n| ------------------------------- | --------------------- | -------------------------------------- |\n| `Esc`, `Ctrl+Q` or `Ctrl+C`     | Quit                  | Exits the application.                 |\n| `Down` or `Ctrl+J`              | Select Next           | Moves to the next selectable item.     |\n| `Up` or `Ctrl+K`                | Select Previous       | Moves to the previous selectable item. |\n| `KeypadBegin` or `Ctrl+1`       | Select First          | Selects the first item.                |\n| `End` or `Ctrl+0`               | Select Last           | Selects the last item.                 |\n| `Enter` or `Ctrl+O`             | Open Selected         | Opens the currently selected item.     |\n| `Delete`, `Ctrl+R`, or `Ctrl+X` | Delete Selected Entry | Deletes the currently selected item.   |\n\nNote: If an input does not match any of the defined keybindings, it is treated as part of a search input.\n\n##### Mouse Interactions\n\n| Mouse Action                   | Description                                                  |\n| ------------------------------ | ------------------------------------------------------------ |\n| Left Click                     | Selects an item. Clicking the same item again opens it.      |\n| Mouse Wheel                    | Scrolls through the list, moving selection up/down.          |\n\n##### Launch Behavior\n\nThere are three launch behaviors:\n\n- `force-classic`: Launch vscode without a dev container\n- `force-container`: Launch vscode with a dev container, error if no dev container is found\n- `detect`: Detect whether the project is a dev container project, and launch the dev container if it is\n\n##### Detection Algorithm\n\nThe detection algorithm determines which dev container config to launch.\n\n- First, check whether a dev container config was specified via the `--config` flag -\u003e launch it\n- Then loads the first dev container it finds\n  - If more than one exists -\u003e show a interactive list of dev containers and let the user select one\n  - If one exists -\u003e launch it\n  - If none exists -\u003e launch vscode normally without a dev container\n\n### Examples\n\n#### Launching a project\n\nYou can launch a project using the default behavior:\n\n```sh\nvscli open                          # open vscode in the current directory\nvscli open .                        # open vscode in the current directory\nvscli open /path/to/project         # open vscode in the specified directory\n```\n\nThe default behavior tries to detect whether the project is a [dev container](https://containers.dev/) project. If it is, it will launch the dev container instead - if not it will launch vscode normally.\n\nYou can change the launch behavior using the `--behavior` flag:\n\n```sh\nvscli open --behavior force-container .  # force open vscode dev container (even if vscli did not detect a dev container)\nvscli open --behavior force-classic .    # force open vscode without a dev container (even if vscli did detect a dev container)\n```\n\nWhen you open a project containing more than one dev container config, you will be prompted to select one:\n![Screenshot showing the dev container selection UI.](.github/images/select.png)\n\nYou can specify which editor command to use with the `--command` flag:\n\n```sh\nvscli open --command cursor .        # open using cursor editor\nvscli open --command code .          # open using vscode (default)\nvscli open --command code-insiders . # open using vscode insiders\n```\n\nAdditional arguments can be passed to the editor executable, by specifying them after `--`:\n\n```sh\nvscli open . -- --disable-gpu        # open the current directory without GPU hardware acceleration\n```\n\nRead more about the editor flags by executing `code --help` (or `cursor --help`, etc).\n\n#### CLI UI\n\nYou can open a CLI-based user interface to display a list of recently opened projects using the `recent` command:\n\n```sh\nvscli recent                                    # open the CLI-based UI to select a recently opened project to open\nvscli recent --command cursor                   # open the selected project with cursor, ignoring the editor stored in history\nvscli recent --behavior force-container         # force open the selected project in a dev container\nvscli recent --command cursor --behavior detect # open with cursor and detect if dev container should be used\nvscli recent --config .devcontainer/custom.json # open with a specific dev container config\nvscli recent -- --disable-gpu                   # pass additional arguments to the editor\nvscli recent --hide-instructions                # hide the keybinding instructions from the UI\nvscli recent --hide-info                        # hide additional information like strategy, command, args and dev container path\n```\n\nThe UI mode provides a convenient way to browse and manage your recent workspaces, with customizable display options and full support for all launch configurations.\n","funding_links":[],"categories":["Rust","cli","Tools"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichidk%2Fvscli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichidk%2Fvscli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichidk%2Fvscli/lists"}