flux · reference

flux Documentation

Everything Flux 0.2.1 can do, written out once. Installation, the full command set, where the cache lives, and what is still missing.

fluxgithub ↗

the complete command set

init·install·uninstall·reinstall·update·list·outdated·info·run·clear

§ 01

Two ways in.

Take the npm package if Node is already on the machine. Take the standalone binary if you would rather not carry a runtime around.

a · global npm package

npm install -g @iamgautamsuthar/flux
npx @iamgautamsuthar/flux --help

Requires Node 18 or later. To update, run the same command again. To remove it, run npm uninstall -g @iamgautamsuthar/flux.

b · standalone binary

curl -fsSL https://raw.githubusercontent.com/callmegautam/flux/main/install.sh | sh
irm https://raw.githubusercontent.com/callmegautam/flux/main/install.ps1 | iex

Self contained, no Node needed. Linux and macOS take the curl script, Windows PowerShell takes irm. The Windows install is per user and needs no administrator rights. To remove it, delete the binary.

prebuilt targets

  • linux-x64Linux, Intel / AMD 64-bit
  • linux-arm64Linux, ARM 64-bit
  • darwin-x64macOS, Intel
  • darwin-arm64macOS, Apple silicon
  • windows-x64Windows, 64-bit

Every release carries these binaries next to a SHA256SUMS file, which both install scripts verify for you.

environment

FLUX_CACHE_DIR
Where downloaded tarballs are kept. Defaults to platform cache directory.
FLUX_VERSION
Read by both install scripts. Defaults to latest release.
FLUX_INSTALL_DIR
Where the standalone binary lands. Defaults to ~/.local/bin · %LOCALAPPDATA%\flux\bin.
§ 02

Commands.

Listed roughly in the order you reach for them. Every alias is shown on the right. Run flux --help for the full set of flags.

  1. initcreate

    Create a package.json in the current directory.

  2. install [package]add

    Install one package and record it in package.json, or install every dependency already listed there.

  3. uninstall [package]remove , rm , delete

    Remove one package, or all of them, from the project and node_modules.

  4. reinstall [package]re , re-i

    Wipe and reinstall one package, or all of them.

  5. update [package]upgrade

    Fetch the latest published version of one package, or all of them.

  6. listls , show

    Print every dependency currently installed.

  7. outdatedout , old , new

    Compare installed versions against what the registry publishes.

  8. info <package>i

    Show registry metadata for a package.

  9. run <script>r

    Run a script defined in package.json.

  10. clearc

    Delete the download cache.

Pass --flux to install to resolve tarballs through the Flux registry instead of npm.

§ 03

One cache directory. Nothing else to configure.

Downloaded tarballs are kept per user, in the place your platform expects them.

cache location

  • Linux$XDG_CACHE_HOME/flux, or ~/.cache/flux
  • macOS~/Library/Caches/flux
  • Windows%LOCALAPPDATA%\flux\Cache

Set FLUX_CACHE_DIR to put them somewhere else, and run flux clear to empty the cache.

§ 04

What Flux does not do yet.

Written out plainly, so you can decide whether that is fine for what you are building.

  1. 01

    Direct dependencies only

    Flux installs what is listed in your package.json. It does not walk the dependency tree, so most real packages will not work end to end.

  2. 02

    No lockfile

    Installs are not reproducible. Two runs of the same project can resolve to different versions.

  3. 03

    No semver range resolution

    A range like ^1.2.3 is not resolved against. Flux installs whatever the registry currently publishes as latest.

  4. 04

    No test suite

    There is no automated coverage yet. Treat every release as unverified until you have tried it yourself.

§ 05

What comes next.

Roughly in the order it matters. None of it is done yet, which is what the empty boxes mean.

  • Full dependency tree resolution
  • A lockfile, for reproducible installs
  • Registry search from the CLI
  • A dependency tree viewer
  • Parallel installs
  • Workspace support
  • Vulnerability scanning

contributing

Open tasks and known bugs sit in the issues tab. Fork the repository, make your change, then run the type check and the build before you open a pull request. The contributing guide has the longer version.