cli-developer

Work on the LenserFight CLI (lf).

Scope

• Source: apps/cli/src/**
• Commands: apps/cli/src/commands/*.ts
• Utilities: apps/cli/src/utils/ (api, output, auth, auth-recovery, ansi, error-reporter, profiles, supabase-client, automation-objects, battle-stream-broadcaster, local-battle-engine, local-battle-paths, local-battle-storage)
• Libraries: apps/cli/src/lib/ (exec-context, safety, telemetry, redact, onboarding, combine-seeds, command-inventory)
• TUI: apps/cli/src/tui/ (dashboard.ts + tui/ink/ — first-party dashboard, default lf behavior; runtime-telemetry — shared with lf top)
• Adapters: apps/cli/src/adapters/

CLI Structure

• src/main.ts — entry point, uses defineCommand + runMain from citty; binary name is lenserfight / lf
• Each command file exports a defineCommand(...) default and is lazy-imported in main.ts
• src/utils/api.ts — callRpc + handleError; all Supabase RPC calls go through here
• src/utils/output.ts — printTable, printJson, truncate; uses consola for logging
• src/utils/auth.ts + src/utils/supabase-client.ts — auth and Supabase client
• src/utils/ansi.ts — ANSI helper A and symbols sym
• src/lib/exec-context.ts — setExecContext / getExecContext for --local / --debug flags
• src/lib/safety/ — assertSafe for input validation
• src/lib/telemetry.ts — telemetry adapter

Command pattern

import { defineCommand } from 'citty';
import consola from 'consola';
import { callRpc, handleError } from '../utils/api';
import { printTable, printJson } from '../utils/output';

const subCommand = defineCommand({
  meta: { name: 'list', description: 'List items.' },
  args: {
    json: { type: 'boolean', default: false, description: 'Output as JSON' },
  },
  async run({ args }) {
    try {
      const data = await callRpc('fn_example', {});
      if (args.json) printJson(data);
      else printTable(['ID', 'Name'], data.map((r) => [r.id, r.name]));
    } catch (err) {
      handleError(err);
    }
  },
});

export default defineCommand({
  meta: { name: 'example', description: 'Example group.' },
  subCommands: { list: subCommand },
});

Registration in main.ts

const main = defineCommand({
  subCommands: {
    example: () => import('./commands/example').then((m) => m.default),
  },
});

Global flags

• --local → sets LF_LOCAL=1 (parsed early via parseGlobalFlagsEarly before citty)
• --debug → sets LF_DEBUG=1
• Default (lf with no subcommand) → opens the first-party TUI dashboard (tui/dashboard.ts)

Constraints

• Never use fetch/axios directly — use callRpc / handleError from utils/api.ts
• Never add NestJS, Prisma, or backend dependencies
• Keep dependency footprint minimal (citty, consola, dotenv)
• Output via printTable / printJson / consola.* — never raw console.log
• Build: pnpm nx build cli | Test: pnpm nx test cli

References

• citty patterns and integration details: REFERENCE.md