@flightlog/cli

Bun-powered host CLI for Flightlog. It runs the local SQLite-backed server, serves the embedded Studio, exposes the HTTP API and MCP endpoint, and provides lifecycle, diagnostics, and bounded query commands.

The CLI runs on the development machine. Application packages such as @flightlog/sdk and @flightlog/react-native send evidence to it; the React Native package does not embed or start this host process.

Requirements

• Bun 1.3 or newer.
• A supported desktop environment when using studio to open a browser.

Run without installing

bunx @flightlog/cli studio

This starts the local daemon if needed and opens the embedded Studio at http://127.0.0.1:4319.

Other common commands:

bunx @flightlog/cli dev
bunx @flightlog/cli status
bunx @flightlog/cli doctor
bunx @flightlog/cli sessions 25
bunx @flightlog/cli latest 25
bunx @flightlog/cli errors 25
bunx @flightlog/cli stop

Set up an application

From an application root, run:

bunx @flightlog/cli init

init reads the local package.json, detects Expo/React Native, Next.js, TanStack, React, Hono, Express, or a generic JavaScript/TypeScript project, and prints its proposed integration before asking for confirmation. It then:

• installs @flightlog/react-native for native apps or @flightlog/sdk for other apps;
• installs @flightlog/cli as a development dependency;
• adds flightlog, flightlog:dev, flightlog:lan, and flightlog:stop scripts when those names are unused; and
• creates src/flightlog.ts/.js/.mjs (or a root equivalent) with a conservative starter configuration.

Existing scripts and integration files are never overwritten. Framework entrypoints are not rewritten because their lifecycle and client/server boundary are application-specific; the command prints the exact import/rebuild follow-up instead.

Useful automation flags:

bunx @flightlog/cli init --dry-run       # inspect only
bunx @flightlog/cli init --yes           # accept noninteractively
bunx @flightlog/cli init --yes --no-install # write setup without bun add

flightlog setup is an alias for flightlog init. Noninteractive environments must use --yes or --dry-run.

Install in a project

bun add --dev @flightlog/cli

Add scripts if the team wants stable project-local commands:

{
  "scripts": {
    "flightlog": "flightlog studio",
    "flightlog:dev": "flightlog dev",
    "flightlog:lan": "flightlog dev --lan",
    "flightlog:stop": "flightlog stop"
  }
}

Then run bun run flightlog. A global installation with bun add --global @flightlog/cli is also supported, but a project-local version is easier to reproduce.

LAN and configuration

Flightlog binds to loopback by default. For a physical device on a trusted local network, run:

bunx @flightlog/cli dev --lan

LAN mode binds to 0.0.0.0, generates missing ingest/admin capabilities, and prints them. Put only the write-only ingest capability in an instrumented application. Keep the admin capability in trusted Studio/API/MCP clients. LAN traffic is unencrypted; never expose this server directly to the internet.

| Variable | Default | Purpose | | --- | --- | --- | | FLIGHTLOG_HOST | 127.0.0.1 | Bind host. Non-loopback requires both capabilities. | | FLIGHTLOG_PORT | 4319 | HTTP port. | | FLIGHTLOG_HOME | ~/.flightlog | Daemon metadata, logs, and default database directory. | | FLIGHTLOG_DB_PATH | $FLIGHTLOG_HOME/flightlog.db | Explicit SQLite database path. | | FLIGHTLOG_INGEST_TOKEN | unset on loopback | Write-only session/event capability. | | FLIGHTLOG_ADMIN_TOKEN | unset on loopback | Query, MCP, and mutation capability. | | FLIGHTLOG_ALLOWED_ORIGINS | loopback development origins | Additional exact browser origins, comma-separated. |

Use flightlog clear --yes only when intentionally deleting all local evidence. See the repository development guide and MCP guide for the complete command and integration reference.