chromasql-ui-cli

Portable ChromaSQL UI powered by the shared chromasql-ui package. Run it locally, pass backend configuration through CLI flags, or publish it as a standalone npm CLI.

Usage

Build once (optional – the CLI will build automatically if .next is missing):

pnpm --filter chromasql-ui-cli build

Run via the CLI (use --help for all options):

pnpm chromasql-ui-cli --help

Or start the UI immediately:

pnpm chromasql-ui-cli --backend-url http://localhost:8000 \
  --collection collection \
  --collections "collection,collection_v2" \
  --page-size 25 \
  --port 4400

Flags map directly to environment variables used by the app:

| Flag / Env Var | Description | | --------------------------------------------------------------------------------- | ---------------------------------------------- | | --backend-url, NEXT_PUBLIC_CHROMASQL_CLI_BACKEND_URL | Base URL for the Research Agent endpoints | | --collection, NEXT_PUBLIC_CHROMASQL_CLI_COLLECTION | Default collection used in the UI | | --collections, NEXT_PUBLIC_CHROMASQL_CLI_COLLECTIONS / --collection-options | Comma-separated list of selectable collections | | --page-size, NEXT_PUBLIC_CHROMASQL_CLI_PAGE_SIZE | Results per page (defaults to 10) | | --title, NEXT_PUBLIC_CHROMASQL_CLI_TITLE | Title used in metadata + UI header | | --description, NEXT_PUBLIC_CHROMASQL_CLI_DESCRIPTION | Description used in metadata + header text |

Other options:

• --port – port for the server (default 4300)
• --dev/--mode dev – run next dev instead of production
• --build – force a production rebuild before next start

Code Structure

apps/chromasql-ui-cli/
├── bin/
│   └── chromasql-ui-cli.js      # CLI entry point - parses flags and starts Next.js
├── src/
│   ├── app/
│   │   ├── layout.tsx            # Root layout - injects runtime config into window
│   │   └── page.tsx              # Main page component
│   ├── lib/
│   │   ├── backend.ts            # Backend API client - reads runtime config
│   │   └── config.ts             # App configuration - reads runtime config
│   └── components/
│       └── app-toaster.tsx       # Toast notification component
└── scripts/
    └── build-for-npm.js          # Build script for npm publishing

How It Works

1. Runtime Configuration Flow

The CLI uses a runtime configuration approach to support dynamic backend URLs with paths (e.g., http://localhost:8000/api/chromasql):

CLI Flag → Environment Variable → Server Runtime → Window Object → Client Code

Step-by-step:

1. CLI parses flags (bin/chromasql-ui-cli.js)

   • Reads --backend-url and other flags from command line arguments
   • Sets environment variables like NEXT_PUBLIC_CHROMASQL_CLI_BACKEND_URL
   • Starts Next.js server with these environment variables

2. Server renders layout dynamically (src/app/layout.tsx)

   • Exports export const dynamic = "force-dynamic" to ensure runtime rendering
   • Reads environment variables at server runtime (not build time)
   • Injects configuration into HTML via window.__CHROMASQL_RUNTIME_CONFIG__

3. Client reads from window object (src/lib/backend.ts, src/lib/config.ts)

   • Client-side code reads from window.__CHROMASQL_RUNTIME_CONFIG__
   • This ensures configuration is available at runtime, not baked into the build

2. URL Path Preservation

Backend URLs with paths are handled correctly using the URL API:

// Input: http://localhost:8000/api/chromasql
const url = new URL(baseUrl);
// url.pathname = "/api/chromasql"

url.pathname = url.pathname.replace(/\/$/, "") + "/indices";
// url.pathname = "/api/chromasql/indices"

// Final URL: http://localhost:8000/api/chromasql/indices ✓

This approach ensures that paths like /api/chromasql are preserved and properly appended with endpoint paths like /indices and /execute.

3. Why Runtime Configuration?

Next.js NEXT_PUBLIC_* environment variables are typically inlined at build time. This means:

• ❌ Build-time approach: The backend URL is baked into the JavaScript bundle during pnpm build
• ✅ Runtime approach: The backend URL is injected when the server starts, allowing different URLs per CLI invocation

Example:

# Build once
pnpm run build:npm

# Run with different backend URLs - both work without rebuilding!
chromasql-ui-cli --backend-url http://localhost:8000/api/chromasql
chromasql-ui-cli --backend-url http://production.example.com/v1/chromasql

Development

You can still run the app with the usual Next scripts:

pnpm --filter chromasql-ui-cli dev

Config values fall back to the environment variables documented above.