CLI Usage

Why use fluxo-cli?

fluxo-cli is a separate npm package from the fluxo-ui library. Use it to cherry-pick individual components into your project as plain source files instead of installing the whole library as an npm dependency. Built for teams that need to vendor UI components — for compliance, customization, third-party-dep policies, or simply to own the code they ship.

Pick what you need, run it, get real .tsx files dropped into ./src/components/fluxo-ui/ (or wherever you point it). Re-run later to pull updates — your local edits are preserved unless you explicitly opt in to overwrite them. Remove components you no longer need with a single command.

Running the CLI

The CLI ships as the fluxo-cli bin inside the standalone fluxo-cli npm package (separate from the fluxo-ui library). Run it with npx — no global install, no runtime dependency added to your project:

npx fluxo-cli add Button TextInput

pnpm dlx fluxo-cli add Button TextInput

yarn dlx fluxo-cli add Button TextInput

add command

Use add for first-time installs and to add new components later. It walks the dependency closure for everything you select, fetches the source from GitHub (inferred from the package's repository field) or a local clone, rewrites every relative import to land cleanly in your install root, vendors the shared theme stylesheets, writes each file atomically, and re-exports everything from <install-root>/index.ts.

# Add components by id (kebab-case or display name)
npx fluxo-cli add button text-input

# Add into a custom path
npx fluxo-cli add button --path ./app/ui/components

# Pre-compile SCSS to CSS at install time
npx fluxo-cli add button --css

# Skip every prompt and overwrite local edits
npx fluxo-cli add button --force

# Launch interactive picker (no ids on argv)
npx fluxo-cli add

[fluxo-cli add]
  Project root: /work/my-app
  Install path: ./src/components/fluxo-ui (created)

Resolving dependencies...
  + button
  + confirm-popover (transitive)
  + tooltip (transitive)
  + link (transitive, internal)

External packages required:
  classnames (present)
  react (peer (assumed available))

Writing 24 file(s) to ./src/components/fluxo-ui/
  + _eui-vars.scss
  + styles/index.css
  + styles/base-theme.css
  + styles/theme-blue.css
  + button/Button.tsx
  + button/Button.scss
  + confirm-popover/ConfirmPopover.tsx
  ...

Updating ./src/components/fluxo-ui/index.ts
  + component: ./button/Button
  + component: ./confirm-popover
  + component: ./tooltip/tooltip-api

Done. Wrote 24 file(s), 0 skipped, 0 conflicts.

update command

Use update to refresh already-installed components from the source (default branch by default). Drift is computed per-file via SHA-256 checksums recorded in fluxo-ui.config.json, so the CLI knows which files you have edited locally and which still match the original source.

# Refresh every installed component (interactive picker pre-selects them)
npx fluxo-cli update

# Refresh only the listed ids
npx fluxo-cli update button modal

# Refresh everything and overwrite locally-edited files without asking
npx fluxo-cli update --force

# Move the install root and refresh in place
npx fluxo-cli update --path ./app/ui/components

[fluxo-cli update]
  Project root : /work/my-app
  Install path : ./src/components/fluxo-ui

Drift summary:
  button         : 1 modified, 0 missing, 0 added  [locally modified]
  modal          : unchanged
  tooltip        : 0 modified, 1 missing, 0 added

Resolving dependencies...
Writing 14 file(s) to ./src/components/fluxo-ui/
  + tooltip/Tooltip.tsx (added missing)
  ~ modal/Modal.tsx (unchanged)
  - button/Button.tsx (skipped, locally modified)

Files preserved due to local changes:
  button/Button.tsx [locally-modified]

Re-run with --force to overwrite locally-edited files.

remove command

Use remove to uninstall components you no longer need. The CLI deletes the component folder, removes the entry from fluxo-ui.config.json, and strips the matching export line from index.ts.

# Interactive picker — choose components to uninstall
npx fluxo-cli remove

# Remove specific components
npx fluxo-cli remove modal tooltip

# Skip the confirm prompt
npx fluxo-cli remove modal --force

[fluxo-cli remove]
Reverse-dependency check

Cannot remove the following components — they are still required by other installed components:
  • tooltip
      ↳ used by button (Button)
      ↳ used by autocomplete (Autocomplete)

  To remove these too, include the dependent component(s) in the same `fluxo-cli remove` command.

  Proceeding with 1 removable component(s) only.

[fluxo-cli remove]
Removing components
  - removed src/components/fluxo-ui/modal
  - removed src/components/fluxo-ui/snackbar

Index updates
  - removed export from index.ts: ./modal
  - removed export from index.ts: ./snackbar

Summary
Removed 2 component(s): modal, snackbar
Hooks, utils, and shared modules were left in place — they may still be used by other components or by your own code.

Styles & themes

Every install vendors a complete styling bundle so your project never depends on the fluxo-ui npm package at runtime. The bundle includes the shared SCSS variables, the base theme stylesheet, and only the brand themes you actually selected.

// Once at your app entry (e.g. main.tsx / app.tsx / _app.tsx):
import './components/fluxo-ui/styles/index.css';
// (replace ./components/fluxo-ui with your install path)

# Pick themes interactively (multi-select shown on first add)
npx fluxo-cli add Button

# Specify themes on the command line (comma-separated)
npx fluxo-cli add Button --themes blue,lara

# Add a new theme to an existing install
npx fluxo-cli update --themes purple

# Compile SCSS to plain CSS at install time
npx fluxo-cli add Button --css

./src/components/fluxo-ui/
  _eui-vars.scss            # shared SCSS variables, mixins, design tokens
  styles/
    index.css               # entry point — import this once in your app
    base-theme.css          # CSS custom properties (always included)
    theme-blue.css          # only the themes you selected
    theme-lara.css
  button/
    Button.tsx
    Button.scss             # @use '../eui-vars' as *;
  modal/
    Modal.tsx
    Modal.scss
  index.ts                  # auto-managed barrel

Interactive flow

When you run the CLI from a TTY without arguments, it walks you through component selection, install path, and any conflicts. Under CI, piped input, or --force, every prompt short-circuits to a sane default so argv-driven usage stays scriptable.

Flags & environment

All flags work on both add and update. Argv positional values are component ids (kebab-case slug or display name).

npx fluxo-cli add button --path ./app/ui/components

npx fluxo-cli update --force

npx fluxo-cli add button --css

npx fluxo-cli add button --no-export

npx fluxo-cli add button --no-export-hooks

npx fluxo-cli add button --no-export-utils

npx fluxo-cli --help

Environment variables

Generated configuration

On the first add, the CLI writes afluxo-ui.config.json at the project root (next to package.json) and an index.ts at the install root. Both files are kept in sync on every subsequent run.

fluxo-ui.config.json

Stable, sorted JSON suitable for git diffs. Commit this file alongside your source.

{
  "version": "1.0.0",
  "path": "./src/components/fluxo-ui",
  "components": {
    "button": {
      "name": "Button",
      "version": "github:shridhar-tl/fluxo-ui@main",
      "checksum": "8d4f...e102",
      "files": [
        { "path": "Button.tsx",  "checksum": "5c1a...771b" },
        { "path": "Button.scss", "checksum": "9e0d...2a44" }
      ],
      "installedAt": "2026-05-02T10:23:11.491Z"
    }
  },
  "lastUpdated": "2026-05-02T10:23:11.491Z"
}

• path — install root, relative to the project root. Always written in forward-slash form so the file stays portable across hosts.
• components.<id>.files[*].checksum — SHA-256 of the file content with CR/CRLF normalized to LF. update compares this against the on-disk file to detect drift.
• components.<id>.checksum — rollup of all per-file checksums. Lets you tell at a glance whether a component matches the source release.
• version — provenance string (e.g. github:owner/repo@branch or local:<path>).
• Legacy filename support. If you previously had fluxo-ui.json, the CLI keeps using that name on writes — it never silently migrates filenames.

Generated index.ts

The CLI parses the existing index, dedupes by specifier, and appends only the missing exports. Your own re-exports, comments, and side-effect imports are preserved.

// Auto-managed by 'fluxo-cli add' / 'fluxo-cli update'
// You can add your own re-exports below — they are preserved.

export * from './button/Button';
export * from './confirm-popover';
export * from './tooltip/tooltip-api';
export * from './hooks/useClickOutside';
export * from './types';

// Your custom additions stay untouched.
export { default as MyCustomBadge } from './my-custom-badge/MyCustomBadge';

Hooks and utils that a component depends on are also re-exported by default. Pass --no-export-hooks or --no-export-utils to suppress just those, or --no-export to skip the index file entirely. Internal helpers (Link, Icon, editor-core, context) are flagged private and never appear in the index.

Conflict resolution

Every file the CLI is about to write is classified into one of five kinds. Two of them auto-write, one is a no-op, and the remaining two are conflicts that fire the per-file resolver. Decisions made via the batch options apply only within their kind so you stay in control even when answering a long stream of prompts.

Common scenarios

End-to-end recipes for the workflows the CLI is built around. Each one is copy-paste ready — no setup required beyond a project with a package.json.

# package.json already exists. No fluxo-ui.config.json yet.
npx fluxo-cli add button text-input --path ./app/ui/components

# Result on disk:
# ./app/ui/components/
#   button/Button.tsx
#   button/Button.scss
#   text-input/TextInput.tsx
#   ...
#   index.ts          (auto-generated)
# ./fluxo-ui.config.json

npx fluxo-cli add modal

# index.ts diff:
# + export * from './modal';
# + export * from './hooks/useFocusTrap';

npx fluxo-cli update

# Files preserved due to local changes:
#   button/Button.tsx [locally-modified]
#
# Re-run with --force to overwrite locally-edited files.

npx fluxo-cli update --force

# Locally-edited files overwritten (1):
#   button/Button.tsx

npx fluxo-cli update --path ./app/ui/components

# fluxo-ui.config.json now has "path": "./app/ui/components".
# After the move, remove the old folder yourself:
rm -rf ./src/components/fluxo-ui

# Linux/macOS
FLUXO_UI_LOCAL_SOURCE=/work/fluxo-ui-fork/src \
  npx fluxo-cli add button modal

# PowerShell
$env:FLUXO_UI_LOCAL_SOURCE = "C:\work\fluxo-ui-fork\src"
npx fluxo-cli add button modal

FLUXO_UI_REF=v1.4.0 npx fluxo-cli update --force

# fluxo-ui.config.json records:
# "version": "github:shridhar-tl/fluxo-ui@v1.4.0"

# 1. Delete the component folder
rm -rf ./src/components/fluxo-ui/timeline

# 2. Remove the export line from index.ts
# - export * from './timeline';

# 3. Remove the entry from fluxo-ui.config.json
# (or run `fluxo-cli update` and skip the missing-folder prompt)

Error messages

Every failure path emits a typed, mode-tagged error with a concrete remediation hint. No raw stack traces, no indistinguishable add-vs-update wording. The exit code is always meaningful (1 for most errors, 2 for partial installs).

[fluxo-cli update] ConfigStateError: fluxo-ui.config.json was not found.
  Hint: Run `fluxo-cli add <component>` first — it creates the config and installs the initial components. `update` only refreshes existing installs.

[fluxo-cli add] UnknownComponentError: No matching components for: my-button, foobar.
  Hint: Run `fluxo-cli add` (without ids) to launch the interactive picker.

[fluxo-cli add] SourceAccessError: ENOTFOUND raw.githubusercontent.com.
  Hint: Verify your internet connection. If GitHub is unreachable, set FLUXO_UI_LOCAL_SOURCE=<path-to-fluxo-ui-src> to install from a local clone.

[fluxo-cli add] PartialInstallError: 0 of 22 files written. 22 missing on source.
  Hint: The source provider could not produce any of the planned files. Re-run with FLUXO_UI_REF=<branch|tag|sha> or check the manifest with `npm run generate-manifest`.

FAQ