vscx 0.1.0

A thin package manager for VS Code extensions distributed via GitHub Releases / VSIX URLs

vscx

A thin package manager for Visual Studio Code (VS Code) extensions.

vscx lets you install and update VS Code extensions that are distributed as .vsix files via GitHub Releases (or a direct URL) with the same one-command ease you get for Marketplace extensions — without publishing to the Marketplace. It is handy while an extension is still in development (pre-release) and for keeping the same extensions in sync across several machines.

vscx does not replace VS Code. Marketplace install/list/update is delegated to the editor CLI; vscx adds source management and an install ledger for GitHub / URL / local-VSIX extensions. It also works with VS Code forks (Cursor, Positron, VSCodium, Windsurf) — see Editors below.

Requires your editor's CLI (code by default) on your PATH. Run vscx doctor to check.

Install

uv tool install vscx
# Restart the terminal if `vscx` is not found.

Quick start (single extension)

If you author an extension and distribute it via GitHub Releases, put these lines in your repository's README and your users are done:

# install the latest pre-release build
vscx install github:OWNER/REPO --pre-release

# update it later
vscx update REPO        # short name, e.g. "shakyo"

No config file is needed for this. Other ways to specify what to install:

Target	Meaning
publisher.extension	Marketplace extension (latest)
publisher.extension@version	Marketplace extension, pinned version
github:owner/repo	latest release's .vsix on GitHub
github:owner/repo@tag	a specific release tag (pinned)
https://.../something.vsix	a direct VSIX URL
path/to/something.vsix	a local VSIX file

Private repositories: set GITHUB_TOKEN.

GITHUB_TOKEN=... vscx install github:owner/private-repo

Local build (extension author inner loop)

npx @vscode/vsce package
vscx install --local        # installs the newest *.vsix in the current dir (--force)

vscx install ./shakyo-0.1.0.vsix installs a specific file. Local installs are never auto-updated and your .vsix file is never deleted.

Channels (stable / pre-release)

vscx has two channels, mirroring VS Code's own --pre-release:

• stable — releases not marked pre-release on GitHub
• pre-release — the newest release, including ones marked pre-release

The channel for a command is decided in this order (first wins):

1. @tag / @version (exact pin — ignores channel)
2. --pre-release / --stable on the command
3. per-extension channel in vscx.toml
4. the machine default (vscx default)
5. built-in default: stable

Set the machine default once per machine (like rustup default):

vscx default              # show current default
vscx default pre-release  # e.g. on your dev machine
vscx default stable

Updating

vscx update shakyo                  # one (or more) by name
vscx update --all                   # all GitHub extensions + Marketplace
vscx update                         # same as --all
vscx update --pre-release           # only pre-release-tracked extensions
vscx update --owner kenjisato       # only github:kenjisato/* extensions

Each GitHub extension is updated along the channel it was installed on. update does not change channels — to switch, re-install with --stable / --pre-release. Tag-pinned extensions are never auto-updated. Marketplace extensions are updated via code --update-extensions, and only when updating everything.

Multiple extensions / multiple machines (manifest)

For an extension set — shared across machines, or distributed by a teacher / team — declare it in a vscx.toml manifest. Like pip install -r, the manifest is always specified explicitly with --file <path>; vscx never auto-reads a vscx.toml from the current directory.

[marketplace]
extensions = [
  "ms-python.python",
  "charliermarsh.ruff@0.5.0",   # @version pins a version
]

[github]
extensions = [
  "someone/their-extension",                                    # follows the default channel
  { repo = "kenjisato/my-extension", channel = "pre-release" }, # track pre-release for your own
  { repo = "kenjisato/frozen-tool", tag = "v0.0.3" },           # pin a tag
]

[vsix]
urls = ["https://example.com/some-extension.vsix"]

vscx install --file ./vscx.toml                    # a project/repo manifest
vscx install --file ~/dotfiles/vscx.toml           # your own fleet (keep it in dotfiles)
vscx install --file ./vscx.toml --pre-release      # force a channel for this run
vscx install --file ./vscx.toml --profile course   # into a VS Code profile

Manifest install only adds/updates; it never removes extensions not listed (there is no prune). Keep the manifest wherever you like (e.g. dotfiles) and point --file at it; each machine picks its own channel with vscx default, so a dev machine can track pre-release while others stay on stable. After the first install, keep extensions current with vscx update.

Removing extensions

By default vscx removes only what it installed (its ledger). Extensions you installed another way (VS Code UI, plain code) need --force.

vscx uninstall <extension-id | github:owner/repo | url>  # one vscx-installed extension
vscx uninstall some.ext --force                          # remove something vscx didn't install
vscx uninstall --file ./vscx.toml                        # the manifest's set (tracked entries)
vscx uninstall --all                                     # everything vscx tracks (the ledger)

Editors (VS Code forks)

vscx's local/GitHub/URL .vsix installs are gallery-agnostic, so they work on any VS Code fork whose CLI accepts --install-extension. Pick the editor CLI (no auto-detection; default is code):

vscx --editor cursor install github:owner/repo   # per-invocation
export VSCX_EDITOR=codium                         # per-shell
# or set `editor = "positron"` in config.toml (see `vscx path`)

Marketplace-id installs on a fork resolve against its gallery (often Open VSX); the .vsix paths above are unaffected.

Other commands

vscx list [--show-versions] [--profile NAME]   # delegates to code --list-extensions
vscx doctor                                    # environment diagnostics
vscx path                                       # show resolved file locations

Files

vscx stores data in OS-standard locations (via platformdirs); run vscx path to see the resolved paths:

• vscx.toml — which extensions to install (a manifest; keep it anywhere and pass it with --file; share it)
• config.toml — this machine's default channel and editor (user_config_dir; do not share)
• state.json — the install ledger (user_state_dir)

Development

uv sync          # install deps (incl. dev group)
uv run pytest    # run the hermetic test suite (no network, no VS Code needed)

See docs/SPEC.md for the full specification.

Note: vscx is unrelated to Microsoft's @vscode/vsce (the official extension packaging tool). vscx installs/manages extensions; vsce builds them.

License

MIT — see LICENSE.

Trademarks

vscx is an independent project and is not affiliated with, endorsed by, or sponsored by Microsoft. "Visual Studio Code" and "VS Code" are trademarks of Microsoft Corporation; "Cursor", "Positron", "VSCodium", and "Windsurf" are trademarks of their respective owners. These names are used only to describe compatibility.