flux · reference

flux Documentation

Everything Flux 0.3.0 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·cache

§ 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 the metadata cache, tarballs and package store are kept. Defaults to platform cache directory.
FLUX_NETWORK_CONCURRENCY
Parallel metadata and tarball requests. Defaults to 16.
FLUX_FS_CONCURRENCY
Parallel filesystem link operations. Defaults to 32.
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, optionally at a version or range, and record it in package.json, or install every dependency already listed there. Pass --save-dev to record it under devDependencies, or --offline to install only from the local store.

  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 every cache layer.

  11. cache <info|dir|clean>

    Show the size of each cache layer, print the cache location, or clean some or all of it.

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

    No lifecycle scripts

    preinstall, install and postinstall are never run, so packages that compile native code at install time will not work.

  2. 02

    Peers are not auto installed

    Peer dependencies are resolved, but you still have to add them to package.json yourself.

  3. 03

    No workspaces

    Monorepos and workspace protocols are not supported yet.

  4. 04

    os and cpu are not enforced

    Platform specific packages install everywhere, whether or not they can run there.

  5. 05

    No store garbage collection

    The store only grows. Run flux cache clean to reclaim space.

§ 05

What comes next.

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

  • Registry search from the CLI
  • A dependency tree viewer
  • 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.