@useactor/cli

Terminal binary and Ink UI for Actor.

Run

pnpm --filter @useactor/cli dev

dev builds the package and launches the binary with --mock.

Run the built binary directly:

pnpm --filter @useactor/cli build
node packages/tui/dist/tui.js

If Apple Silicon is missing the ripgrep optional dependency:

pnpm install --force --config.optional=true

Source Layout

src/
  tui.ts          # node binary entrypoint
  index.ts        # package public exports
  cli/            # actor command launchpad and subcommands
  auth/           # OpenAI auth setup and login UI
  session/        # interactive session/runtime wiring
  tui/            # production Ink UI
  tui-spikes/     # reference renderer experiments

cli is the launchpad for the actor binary. It handles --help, --mock, --model, and subcommands like auth, projects, personas, permissions, integrations, and feedback. With no subcommand, it starts the interactive session.

session creates the runtime session, selects provider/project/persona context, wires persistence, handles connect actions, and bridges runtime events into the interactive UI or non-TTY fallback output.

tui is the actual terminal UI. Keep visual Ink components in components/, the top-level UI controller in actor-tui.tsx, and UI-local helpers in lib/.

tui-spikes is preserved reference work for alternative renderers. It is not part of the production path.

TUI Folder

src/tui/
  index.tsx
  actor-tui.tsx
  components/
  lib/
    __tests__/
    input.ts
    input-keys.ts
    model-options.ts
    pickers.ts
    slash-commands.ts
    state.ts
    types.ts

actor-tui.tsx owns the UI controller logic: keyboard routing, prompt submit, model/connect picker actions, slash command actions, and approval decisions.

components/ contains Ink render components only.

lib/ contains UI-local state and formatting helpers:

• input.ts: prompt editing and cursor math.
• input-keys.ts: terminal key normalization.
• model-options.ts: provider/model labels for the model picker.
• pickers.ts: picker item generation and navigation helpers.
• slash-commands.ts: slash command menu data/filtering.
• state.ts: transcript and permission prompt state transitions.
• types.ts: UI-only types shared by the TUI layer.

Checks

pnpm --filter @useactor/cli check-types
pnpm --filter @useactor/cli test
pnpm --filter @useactor/cli build
pnpm --filter @useactor/cli smoke:built