CLI Reference

Every command, flag, and example — sourced from the codebase.

Quick Reference

Command	What it does
`flux server start`	Start the Flux server (stores recordings in Postgres)
`flux auth`	Authenticate the CLI against a Flux server
`flux run <file>`	Run a TS/JS file — as a script or a persistent HTTP server
`flux dev <file>`	Dev server with hot reload on file changes
`flux tail`	Stream live requests as they arrive
`flux logs`	List recorded executions (filterable)
`flux why <id>`	Understand why a request failed
`flux trace <id>`	Full execution trace with IO checkpoints
`flux replay <id>`	Re-run with recorded checkpoints — no real IO
`flux resume <id>`	Re-run with real IO — commits to database
`flux config`	Read/write CLI config (url, token)
`flux add <pkg>`	Add npm packages to deno.json
`flux check`	Check code compatibility with the Flux runtime
`flux status`	Overall Flux health check
`flux ps`	Show managed Flux processes

flux server

Manages the Flux server process. The server stores all execution records in Postgres and exposes the gRPC API used by the CLI and runtime.

flux server start

$ flux server start --database-url postgres://user:pass@localhost:5432/flux

  starting server binary ~/.flux/bin/flux-server

Flag	Default	Description
`--port`	50051	gRPC port to listen on
`--database-url`	env: DATABASE_URL	Postgres connection string (required)
`--service-token`	env: FLUX_SERVICE_TOKEN, falls back to `dev-service-token`	Auth token for clients
`--release`	false	Use release-mode binary

flux server restart

Stops the running server then starts it fresh with the given flags.

$ flux server restart --database-url postgres://user:pass@localhost:5432/flux

flux auth

Save credentials so every CLI command can reach the Flux server. Prompts for a token if not provided.

$ flux auth --url http://localhost:50051

  Service token: ••••••••••
  authenticated against http://localhost:50051 using token auth
  saved CLI auth config
  server:  http://localhost:50051

Flag	Description
`--url <URL>`	Flux server URL (required)
`--token <TOKEN>`	Service token — if omitted, you'll be prompted
`--skip-verify`	Save credentials without verifying against the server

flux config

Read or write CLI config stored in ~/.flux/config.json.

$ flux config get
url=http://localhost:50051
token=dev-service-token

$ flux config get token
dev-service-token

$ flux config get url
http://localhost:50051

$ flux config set token my-new-token
saved config value

Key	Description
`url` (alias: `server`)	Flux server URL
`token`	Service token

flux run

Run a TypeScript or JavaScript file using the Flux runtime. Works as:

A plain script (top-level code runs and exits)
A persistent HTTP server if export default is a Hono app or Deno.serve() is called

$ flux run index.ts

# with explicit input for a default handler
$ flux run index.ts --input '{"email":"test@example.com"}'

# keep alive as HTTP server
$ flux run index.ts --serve --port 8080

Flag	Default	Description
`[ENTRY]`	—	Entry TypeScript/JavaScript file
`--artifact <FILE>`	—	Use a pre-built Flux artifact JSON instead of a file
`--input <JSON>`	`{}`	JSON passed to the default handler
`--serve` / `--listen`	false	Keep alive as HTTP listener
`--port`	3000	HTTP port when serving
`--host`	127.0.0.1	Bind host when serving
`--url`	env: FLUX_SERVICE_TOKEN	Flux server URL (optional, for recording)
`--token`	—	Service token (optional)
`--release`	false	Use release-mode runtime binary

flux dev

Like flux run --serve but with hot reload — restarts automatically on file changes.

$ flux dev index.ts

  env       /Users/me/my-app/.env
  flux dev  /Users/me/my-app/index.ts
  watching  /Users/me/my-app
  [flux dev] started pid 12345

Flag	Default	Description
`[ENTRY]`	—	Entry TypeScript/JavaScript file
`--port`	3000	HTTP port
`--host`	127.0.0.1	Bind host
`--poll-ms`	500	How often to check for file changes (ms)
`--watch-dir`	entry's parent dir	Directory to watch for changes
`--url`	—	Flux server URL (optional)
`--token`	env: FLUX_SERVICE_TOKEN	Service token (optional)
`--release`	false	Use release-mode binary

flux tail

Stream live requests as they arrive. Shows status, method, path, duration, and the short execution ID.

$ flux tail

  streaming live requests — ctrl+c to stop

  ✓  ok     POST /orders   88ms  a1b2c3d4
  ✗  error  POST /orders   21ms  e9f66586
     └─ HTTP Internal Server Error (500)

Flag	Description
`--url <URL>`	Flux server URL (overrides saved config)
`--token <TOKEN>`	Service token (overrides saved config)
`--project-id <ID>`	Filter to a specific project

flux logs

List recorded executions from the server. Supports filtering by status, path, time, and free-text search.

$ flux logs

  TIME      METHOD  PATH               STATUS   DURATION  ID
  14:22:01  POST    /orders            ✓ ok      88ms      a1b2c3d4
  14:22:09  POST    /orders            ✗ error   21ms      e9f66586

  showing last 50 — flux logs --limit 100 for more

# Filter examples
$ flux logs --status error
$ flux logs --path /orders
$ flux logs --since 1h
$ flux logs --search "productId"
$ flux logs --limit 100

Flag	Default	Description
`--limit <N>`	50	Max rows to show
`--status <STATUS>`	—	Filter by status: `ok` or `error`
`--path <PATH>`	—	Filter by path substring
`--since <DURATION>`	—	Only show entries newer than duration: `30m`, `2h`, `1d`
`--search <TEXT>`	—	Search across path, method, error, and execution ID
`--project-id <ID>`	—	Filter to a specific project
`--url` / `--token`	—	Override saved server config

flux why <id>

Understand why a request failed — shows the error, console output, and a suggestion.

$ flux why e9f66586

  POST /orders  ✗ error  21ms  e9f66586

  function threw before any IO
  error   Internal Server Error

  error body
    Internal Server Error

  console
    › "2026-03-22T08:36:09.048Z"
    › Incoming body: {"email":"test@example.com","productId":"101"}
    ✗ Error: productId must be a number
    at Array.<anonymous> (index.ts:45:11)

  check input validation and early-exit logic

Flag	Description
`EXECUTION_ID`	Execution ID (required) — copy from `flux tail` or `flux logs`
`--url` / `--token`	Override saved server config

flux trace <id>

Full execution trace: request/response bodies, console output, and every IO checkpoint (Postgres queries, HTTP calls, Redis commands, TCP connections, timers).

$ flux trace e9f66586

  POST /orders  error  21ms  e9f66586
  error  HTTP Internal Server Error (500)

  request
    (hidden, use --verbose)

  response
    (hidden, use --verbose)

  console
    ✗  Error: productId must be a number

  no checkpoints recorded

# Show full request/response bodies
$ flux trace e9f66586 --verbose

# Example trace with Postgres checkpoint
$ flux trace a1b2c3d4

  POST /orders  ok  88ms  a1b2c3d4

  checkpoints
  [0] POSTGRES  localhost:5432  43ms  → 1 rows  INSERT INTO orders ...

Checkpoint types shown: POSTGRES, HTTP, TCP / TCP+TLS, REDIS, TIMER.

Flag	Description
`EXECUTION_ID`	Execution ID (required)
`--verbose`	Show full request/response bodies instead of "(hidden, use --verbose)"
`--url` / `--token`	Override saved server config

flux replay <id>

Safe, no real IO. Re-runs a recorded request against your current code using only recorded checkpoints. Stops cleanly at IO boundaries where no checkpoint was recorded. Use this to verify a fix without touching your database.

$ flux replay e9f66586

  replaying e9f66586
  ✓ using updated code

  STEP 0 — POST /orders

  execution
    ✗ original execution failed before reaching external IO
    ✓ replay progressed beyond original failure point

  ⏸ stopped at external boundary: POSTGRES
  reason
    no recorded checkpoint available for this postgres call
    replay never touches the real world

  ✓ your code fix is working — replay progressed further than the original

  next
    → run flux resume e9f66586 to continue with real IO

# Show diff vs original execution
$ flux replay e9f66586 --diff

# Start replay from a specific checkpoint index
$ flux replay e9f66586 --from-index 2

Flag	Default	Description
`EXECUTION_ID`	—	Execution ID to replay (required)
`[ENTRY]`	auto-detected	Entry file to use (defaults to project entry)
`--diff`	false	Show comparison vs original execution
`--from-index <N>`	—	Start replay from checkpoint index N
`--commit`	false	Commit the result to the server
`--validate`	false	Validate replay output matches original
`--explain`	false	Explain the replay plan without running
`--ignore <PATHS>`	—	Comma-separated paths to ignore during replay
`--verbose`	false	Show detailed runtime output
`--port`	3000	Runtime HTTP port
`--url` / `--token`	—	Override saved server config

replay = investigation. resume = action.

Replay is deterministic and safe — it cannot mutate your database or call external services. Use flux resume when you're convinced the fix is correct.

flux resume <id>

Real IO — writes to database, calls external services. Re-runs a request from a checkpoint boundary with live execution. Generates a new execution ID so the original record is preserved.

$ flux resume e9f66586

  resuming e9f66586…

  ⚠  executing with real side effects
     • database writes will be applied

  STEP 0 — POST /orders

  input
    email:      test@example.com
    productId:  101

  execution
    ✓ validation passed
    ✓ database write applied

  result
    ✓ request succeeded (200)

  output
    id:     9b887ab1
    email:  test@example.com

  difference vs original
    original:  ✗ failed
    now:       ✓ completed successfully

  ✓ original failure recovered

# Resume from a specific checkpoint index
$ flux resume e9f66586 --from 2

Flag	Description
`EXECUTION_ID`	Execution ID to resume (required)
`--from <INDEX>`	Start from checkpoint index N (default: 0)
`--url` / `--token`	Override saved server config

flux status

Overall health check — shows whether the server is reachable and reports any issues.

$ flux status

flux ps

Show managed Flux processes (server, runtimes).

$ flux ps

flux add

Add npm packages to your project's deno.json import map.

$ flux add hono zod

  adding   hono as npm:hono
  adding   zod as npm:zod
  updated  /Users/me/my-app/deno.json

# Specific version
$ flux add hono@4.0.0

  adding   hono as npm:hono@4.0.0
  updated  /Users/me/my-app/deno.json

Packages can be referenced as npm:package or https:// URLs. After adding, import via the short name:

import { Hono } from 'hono'   // resolves from deno.json import map

flux check

Scan your TypeScript/JavaScript project for compatibility issues with the Flux runtime before running or deploying.

$ flux check index.ts

  checked   /Users/me/my-app/index.ts
  modules   12
  artifact  a3f9c8...

# With an error:
  error [node_import] index.ts: node: imports are not supported: node:crypto

# With a warning:
  warning [unsupported_global] index.ts: Buffer may not be available in Flux runtime

Exit code 1 = errors found. Exit code 0 = compatible. See Compatibility for the full list of diagnostic codes.

Flag	Description
`[ENTRY]`	Entry file to check (auto-detected if omitted)

The debugging workflow

Question	Command
What requests are failing right now?	`flux tail`
Show me recent failures	`flux logs --status error`
Why did this request fail?	`flux why <id>`
What IO did it do?	`flux trace <id>`
See full request body	`flux trace <id> --verbose`
Does my fix work?	`flux replay <id>`
Show diff vs original	`flux replay <id> --diff`
Apply the fix for real	`flux resume <id>`