@slop-lab/dim-installer

@slop-lab/dim-installer is a thin installer/facade for the real DIM CLI, @slop-lab/dim-cli. Its own executable is also named dim. It installs the CLI and plugins with exact versions via npm, requires no sudo, and does not duplicate DIM's command tree: anything other than its three installer-owned commands is forwarded as-is to the installed DIM CLI.

DIM installs and runs on Linux hosts only. macOS, Windows, and Docker Desktop hosts are not supported.

Getting the dim command

Two supported ways to run it, both pinned to an exact version:

mise use --raw --global 'npm:@slop-lab/[email protected]'
dim install-cli

npx '@slop-lab/[email protected]' install-cli

With mise, plain dim ... keeps working afterwards for both installer commands and (once installed) the real CLI. With npx, repeat the pinned npx '@slop-lab/[email protected]' ... invocation each time you need the installer.

The mise-installed facade uses an existing supported Node.js 24 or 26 when one is on PATH. Otherwise it runs itself through mise exec node@24, which installs Node.js 24 on demand without adding it to the global mise configuration. Consequently, the first dim invocation may require network access and take longer while Node.js is downloaded. A direct --local-bin CLI symlink bypasses this facade bootstrap and still requires Node.js 24 or 26 on PATH.

Never use latest for software that controls development containers or loads executable plugins — always pin an exact, reviewed version.

Current mise releases ask for confirmation when an npm package is below aube's weekly-download threshold. Use --raw as shown above: without it, mise may hide the confirmation prompt and leave no way to enter Y. Review the exact pinned DIM release, then approve that direct package when prompted. The approval does not exempt low-download transitive dependencies.

Losing access to the installer

If you install the CLI in direct-PATH mode (see below), ~/.local/bin/dim becomes a symlink straight to the real DIM CLI. Once that dim is the one your shell resolves first, bare dim runs the real CLI directly — the facade, and with it dim installer / dim install-cli / dim install-plugin, is no longer reachable that way. To run installer-only commands again (upgrading, adding a plugin, repairing), go back to an explicit, pinned npx call:

npx '@slop-lab/[email protected]' install-cli
npx '@slop-lab/[email protected]' install-plugin '@example/[email protected]'

If both a mise-provided facade and a direct-PATH dim are on PATH, normal PATH order decides which one runs; use which -a dim to check. In particular, ~/.local/bin/dim may shadow mise's shim. That direct symlink runs the CLI without the installer facade, so installer commands are no longer available through that dim, and changing the version selected by mise does not change the directly linked CLI. Keep the mise-managed facade default unless that separation is intentional.

Commands

The installer owns installation and installed-plugin lifecycle commands. Everything else is passed through unchanged to the installed DIM CLI (for example dim plugin ... is always a DIM CLI command, never handled here).

dim installer                Open the interactive installer (TTY only)
dim install-cli [options]    Install/upgrade the DIM CLI
dim install-plugin PACKAGE@EXACT_VERSION...
                              Install and enable one or more plugins
dim enable-plugin PACKAGE... Enable installed plugins
dim disable-plugin PACKAGE... Disable installed plugins without uninstalling
dim remove-plugin PACKAGE... Uninstall plugins

Bare dim (no arguments) is an alias for dim installer only while no DIM CLI is configured yet. Once one is, bare dim behaves like every other command instead — it's forwarded to the installed CLI, which prints the same thing as dim --help. This keeps dim installer as the one way to reopen the installer prompt after that point.

Running dim installer with no TTY does not hang waiting for input — it prints usage and exits with an error instead.

Interactive install

npx '@slop-lab/[email protected]'

Prompts for what to install (CLI, plugin(s), or both), then — for the CLI — whether to expose a ~/.local/bin/dim symlink, and — for plugins — space-separated, exact-version package specifiers.

dim install-cli

Usage: dim install-cli [options]

Options:
  --no-local-bin  Install privately for facade use without ~/.local/bin/dim
  --local-bin     Create a managed dim symlink in the user bin directory
  --prefix PATH   Use PATH/bin for the managed symlink (default: ~/.local)
  -h, --help      Show this help

--local-bin and --no-local-bin are mutually exclusive. See "CLI install modes" below for what each one does and which is the default.

dim install-plugin

Usage: dim install-plugin PACKAGE@EXACT_VERSION...

Options:
  -h, --help  Show this help

dim install-plugin '@example/[email protected]'

Specifiers must be pinned to an exact version ([email protected]); this command does not resolve latest or ranges. Installed packages are recorded in plugins.json under the unified runtime. Install the CLI first; plugin installation fails without it because npm has no host core against which to validate the plugin's peer dependency.

Local .tgz inputs are copied into DIM's managed runtime/sources directory, so a later CLI replacement does not depend on the original download or build directory. Manage an installed plugin without editing runtime files directly:

dim disable-plugin '@example/dim-plugin'
dim enable-plugin '@example/dim-plugin'
dim remove-plugin '@example/dim-plugin'

Disable keeps the package installed but stops loading it. Enable requires an installed package. Remove uninstalls it and deletes its activation entry.

CLI install modes

Either mode installs the CLI, core, and enabled plugins into one private, stable npm project that is never on PATH directly:

$XDG_DATA_HOME/dim/runtime/current/node_modules/.bin/dim

(falling back to ~/.local/share/dim/runtime/current/... when XDG_DATA_HOME is unset). Registry installs must match the installer's own version. Replacements are installed and verified in a temporary sibling directory before current is switched; temporary and backup directories are removed after success.

Direct PATH (--local-bin) additionally creates or replaces a symlink in the bin directory pointing at that versioned executable:

~/.local/bin/dim -> $XDG_DATA_HOME/dim/runtime/current/node_modules/.bin/dim

Use --prefix PATH to use PATH/bin/dim instead of ~/.local/bin/dim. Once this symlink is what PATH resolves, dim runs the real CLI directly and the facade/installer commands are no longer reached that way (see above).

The installer only ever creates, replaces, or removes a dim at that path if it is already a symlink pointing inside its own managed runtime data directory. If some other file or symlink is already there — including a different dim installation — it stops with a conflict error instead of overwriting it; inspect and clean up the existing path yourself, then re-run.

Proxied (--no-local-bin) installs to the same stable directory but does not touch PATH at all. The facade instead records the absolute executable path in its config and proxies every non-installer command to it.

dim install-cli --no-local-bin

For local DIM development, build a package bundle and install it behind the same facade without publishing or replacing the mise shim:

bash scripts/pack-local-packages.bash /tmp/dim-packages
dim install-cli --local-packages /tmp/dim-packages --no-local-bin

The bundle's installer package is ignored so the currently selected facade remains responsible for dispatch. The installed CLI reports the version stored in config; package-manifest versions are not used to construct paths. Plugins share the runtime's @slop-lab/dim-core, whose exact peer dependency is checked by npm before installation succeeds.

Default: under mise, --no-local-bin is the default; everywhere else, --local-bin is the default. The explicit flag always wins over this detection. The interactive installer prints the direct-mode risks before it offers --local-bin behavior under mise. Its yes/no question phrases the recommended mode positively, so answering Y or pressing Enter chooses the environment-specific default.

dim --help / dim --version

Behavior depends on whether the real CLI is installed (per the facade's config, not just PATH):

• Not installed: dim --help prints facade-only help (this package's own usage, not a pretend DIM CLI help). dim --version prints:

  DIM installer 0.8.0
  DIM CLI: not installed

• Installed: dim --help is forwarded to the real CLI's own --help. dim --version prints:

  DIM CLI 0.8.0 (via DIM installer 0.8.0)

  with a warning if the configured version no longer matches what's actually installed (run dim install-cli again to repair).

Any other command with no CLI installed fails fast with exit code 2 and a message pointing at dim install-cli, instead of guessing at some other dim on PATH.

Configuration file

Installer state (proxied CLI executable path/version, plugin home) is kept in:

${XDG_CONFIG_HOME:-$HOME/.config}/dim/config.json

or the path given by DIM_CONFIG_PATH. This file is also read by the DIM CLI itself (for example to locate the plugin home), so treat it as shared state rather than installer-private cache. You normally don't need to edit it by hand — re-run dim install-cli / dim install-plugin to change what it points at.

What this does not do

The installer only installs the DIM CLI and DIM plugins. It does not install Docker, a workspace runtime backend, or the DIM workspace image; see the repository's host setup guide for those prerequisites.

Before adopting DIM or any plugin, follow the mandatory adoption and trust requirements. See the plugin documentation and @slop-lab/dim-cli for the next steps.