Docs

GaleWind is a package manager for Node.js. This page covers the commands you'll reach for most, plus the parts of gwin that are easy to miss — caching, workspaces, and publishing.

Getting started

# install gwin
npm install -g galewind-npm

# confirm it's on your PATH
gwin -v

This installs two commands: gwin, the main tool, and gwix, for running a workspace package's CLI without adding it to your PATH. Global installs live in ~/.galewind/global, and gwin adds ~/.galewind/global/bin to your PATH the first time you install, update, or promote something globally — restart your shell afterward for it to take effect. On Windows, gwin writes setup steps to ~/.galewind/PATH_SETUP.txt instead.

gwin -v also checks npm for the latest release and shows the update command if you're behind. Gwin repeats that check quietly after every gwin i, staying silent unless a newer version is out.

Everyday commands

gwin i	Install everything in the current folder's package.json
gwin i -g <pkg>	Install a package globally, onto your PATH
gwin i <pkg>	Install a package into the current project
gwin rm <pkg>	Remove a package (add -g for global)
gwin update <pkg>	Update a package to its latest version
gwin ls	See what's installed (add -g for global)
gwin outdated	Check for newer versions of what you have
gwin search <term>	Search npm for a package by name
gwin init	Create a starter package.json
gwin run <script>	Run a script from package.json (no name lists what's available)
gwin ci	Clean, exact reinstall from your lockfile
gwin clean [--lock]	Remove node_modules, optionally the lockfile too

How the cache works

Gwin keeps a shared download cache, plus a short-lived in-memory record of package listings it has already looked up. Run gwin i again a few minutes later and it reuses that listing instead of asking the registry from scratch. If your lockfile's pinned versions are already sitting in the cache, gwin skips the registry lookup entirely and installs straight from disk — the fastest path is a clean gwin ci, or a gwin i right after one, on a project that hasn't changed.

# see how much space the cache is using
gwin cache size

# empty it
gwin cache clean

Once the cache grows past a size cap (3GB by default), gwin evicts whichever cached packages have been used the least, based on hit counts and last-used times tracked in a .pkg_cache file — not just whatever happens to be oldest on disk. Override the cap with the GWIN_CACHE_MAX_BYTES environment variable, in bytes.

Workspaces

If you keep several small projects in one parent folder, register that folder once so they can all share installed packages instead of each downloading its own copy.

gwin -w "~/Projects" name "my-projects"

# install / update / remove for the whole folder
gwin -w my-projects i lodash
gwin -w my-projects update lodash
gwin -w my-projects rm lodash

# list, forget, or exactly reinstall a workspace
gwin workspaces
gwin workspaces rm my-projects
gwin -w my-projects ci

A project can use a package that isn't in its own workspace if it's already installed in another workspace you've registered — gwin reuses that copy rather than downloading again. Bind to a workspace to stop repeating -w on every command:

gwin bind -w my-projects
gwin i lodash   # no -w needed
gwin unbind

Packages installed into a workspace aren't automatically on your PATH the way global installs are — use gwix to run their CLIs:

gwix -w my-projects eslint .
gwix -w my-projects cowsay "moo"

Older scripts may still use -p, the original name for this flag. It's kept as a legacy alias, off by default — turn it on with gwin --projects-enable if you're not ready to switch. New scripts should use -w.

Linking & promoting

Point one workspace at another so it reuses an existing copy of a package instead of downloading it again:

gwin link add my-other-workspace
gwin link ls
gwin link rm my-other-workspace

With no workspaces added to the link list, gwin checks every registered workspace instead — the list just narrows the search. To move a package already installed in a project or workspace into your global install as a standalone copy, use promote:

gwin promote lodash
gwin -w my-projects promote lodash
gwin promote *   # promote everything

Install scripts

Gwin never runs a package's preinstall/install/postinstall scripts automatically — it tells you if a package has some and skips them. Add --scripts if you trust the package and want them to run:

gwin i node-sass --scripts

Login & publishing

gwin login and gwin publish talk to the npm registry directly, keeping their own login separate from npm login — saved to ~/.galewind/auth.json.

gwin login           # browser flow — security keys, passkeys, 2FA apps
gwin login --legacy  # username/password instead
gwin whoami
gwin logout
gwin publish

gwin login opens the same web login flow the npm CLI uses by default. Registries that don't support it fall back to a username/password prompt automatically. Running gwin publish while logged out launches gwin login for you.

Add a .gwinignore file, styled like .gitignore, to control what gwin publish reports as included. node_modules/, .git/, and a few others are always left out.

Settings

GWIN_REGISTRY	Point gwin at a different registry, e.g. a private company one
GWIN_CACHE_MAX_BYTES	Size cap for the shared download cache, in bytes (default 3GB)

Run gwin --help, or just gwin with nothing else, any time for the full command list.