@lite-fsm/cli

Alpha command line tools for lite-fsm. The lite-fsm binary can create starter React projects, add generated-store machines, export a project graph JSON document, and run a local Visualizer session for a TypeScript project.

The CLI uses @lite-fsm/graph for static analysis. It does not run your app, call reducers, execute effects, or evaluate user code.

Install

npm install --save-dev @lite-fsm/cli

After installation, the lite-fsm command is available.

Commands

| Command | Purpose | | -------------- | ---------------------------------------------------------------------- | | create | Create a starter Next.js or Vite React project wired to lite-fsm. | | add-machine | Add a domain machine to a generated src/store. | | export-graph | Build a project graph and write a JSON export document. | | visualize | Build a project graph and launch the bundled local Visualizer session. |

Create a Project

Create a Next.js starter:

lite-fsm create my-app --template next

Create a Vite starter:

lite-fsm create my-app --template vite

Create a starter in the current directory:

lite-fsm create . --template next

Tailwind CSS is enabled by default. To create the same starter without Tailwind:

lite-fsm create my-app --template vite --css none

The generated project includes TypeScript, alias @/*, @lite-fsm/core, @lite-fsm/react, @lite-fsm/middleware, immer, and a minimal store under src/store.

Add a Machine

From the root of a project created by lite-fsm create, add a domain machine:

lite-fsm add-machine user-session

This creates src/store/machines/user-session.ts, registers userSession in src/store/index.ts, and adds userSession.Events to src/store/types.ts.

The v1 command accepts names in kebab-case, snake_case, or camelCase and always uses the generated store layout under src/store.

Export a Graph

lite-fsm export-graph --entry store/index.ts --out lite-fsm.graph.json --tsconfig tsconfig.json

Minimal source shape:

// store/index.ts
import { MachineManager, createMachine } from "@lite-fsm/core";

export const lamp = createMachine({
  config: {
    OFF: { SWITCH: "ON" },
    ON: { SWITCH: "OFF" },
  },
  initialState: "OFF",
  initialContext: {},
});

export const manager = MachineManager({ lamp });

The export document includes the graph, project files, source hashes, CLI diagnostics, and optional source text when --include-source is passed.

Run the Visualizer

lite-fsm visualize --entry store/index.ts

By default, visualize starts a local server on 127.0.0.1:3030, opens a browser, and keeps the process running until interrupted.

Useful options:

lite-fsm visualize --entry store/index.ts --tsconfig tsconfig.json --port 3031 --no-open

Options

create:

• <project-name> - required relative target directory, or . for the current directory. Nested paths such as apps/demo are supported when the parent directory already exists.
• --template <next|vite> - required framework template.
• --css <tailwind|none> - styling preset, defaults to tailwind.
• --package-manager <pnpm|npm|yarn|bun> - package manager for scaffold, install, and next steps, defaults to npm.
• --install / --no-install - install dependencies after generation, defaults to --install.

add-machine:

• <name> - required machine name in kebab-case, snake_case, or camelCase. The command runs relative to the current working directory and supports the store shape generated by lite-fsm create.

export-graph:

• --entry <path> - required TypeScript entry file where the selected MachineManager(...) is visible.
• --out <path> - required output JSON path.
• --tsconfig <path> - optional explicit TypeScript config.
• --include-source - embed discovered source file text in the JSON document.

visualize:

• --entry <path> - required TypeScript entry file.
• --tsconfig <path> - optional explicit TypeScript config.
• --port <number> - local Visualizer port, defaults to 3030.
• --no-open - print the session URL without opening a browser.

Documentation

• Full documentation
• CLI package guide
• CLI API reference