vlt setup

Usage:

$ vlt setup [<account>]
$ vlt setup --path

Configure the registry aliases for your vlt.io account so that vlt install and vlx work out of the box.

The npm registry alias has no built-in URL, so a fresh project can't resolve bare specifiers (like vlt install express) until a registry is configured. vlt setup is the guided way to do that: sign up or log in at https://www.vlt.io first, then run the wizard.

What it does

1. Prompts for your vlt.io account (or organization) slug if not passed as an argument.
2. Stages the two registry aliases every account is provisioned with:
   • npm → https://registry.vlt.io/<account>/npm/ (the default bare-spec alias)
   • main → https://registry.vlt.io/<account>/main/ (your account's primary private registry)
3. Optionally authenticates against those registries via the browser web-login flow. A single token covers every registry on your account, so the browser opens once and the token it returns is saved for both the public npm mirror and your private main registry.
4. Loops to let you add any additional custom aliases (for partner or team registries), optionally authenticating against each.
5. Writes the staged aliases into your user vlt.json (merging with, not clobbering, existing entries). Aliases that already live in a vlt.json are left where they are, so a project-local alias does not get copied into your user config (or the reverse).
6. If your keychain has a token for only one of npm / main, copies it to the other. Existing tokens are never overwritten, and VLT_TOKEN* environment tokens are never saved. This also runs with --yes or when you skip authentication.
7. In a terminal, if the global bin folder isn't on your PATH or set up yet, asks Setup PATH for global installs? (Y/n). Yes adds it (see below); no skips it, and vlt setup --path does just that step later. Not asked with --yes, without a terminal, or with --no-modify-path.

If the project you run this in configures its own registries, the output says so: project config takes precedence for registry selection, so writing your user config would not take effect there. Re-run with --config=project to configure that project.

Options

Examples

Interactive setup for an account:

$ vlt setup my-account

Unattended setup (for CI or setup scripts):

$ vlt setup my-account --yes --registries team=https://registry.example.com/

Write to the project's vlt.json instead of your user config:

$ vlt setup my-account --config=project

Add global bins to your PATH:

$ vlt setup --path

Add global bins to your PATH

Adds the global bin folder (see Global installs) to your PATH in new terminals. vlt setup offers it at its end; vlt setup --path runs just that step (after skipping it, or on an older setup). vlt install -g also offers it once, in a terminal, when that folder isn't on your PATH (--yes accepts without asking).

On macOS and Linux, it writes <global-dir>/env (and env.fish), which adds the folder to PATH, and a section that loads it into your shell config:

# vlt
if [ -f "$HOME/.local/share/vlt/global/env" ]; then . "$HOME/.local/share/vlt/global/env"; fi
# vlt end

On Windows it adds the folder to the start of your user Path (Edit environment variables for your account) instead, whatever the shell. If the folder changes, the new one is added and the old entry stays.

• Asks first, unless --yes (required without a terminal).
• Backs files (on Windows, the old Path) up to <global-dir>/backups.
• Running it again changes nothing. On macOS and Linux, if the folder changes, only env is rewritten.
• Already in your PATH: nothing changes.
• A different # vlt section is replaced.
• A symlinked file (dotfile managers) is followed: its target is edited and the link is kept.
• --global-bin-dir=<path> picks the folder.
• VLT_NO_MODIFY_PATH=1 (any value but 0), or --no-modify-path, turns this and the install offer off (the line to add is printed instead), and skips the vlt setup prompt.
• Other shells (like nu) aren't supported on macOS and Linux yet: it prints the line to add.

Open a new terminal afterwards (on Windows, also restart editors like VS Code), or run the line it prints.

See also

• Working with Named Registries
• Authentication
• vlt login
• Global Installs