@factory/cli

Factory CLI - Demo Edit

A hybrid command-line interface that runs either:

• Interactive TUI – a full-screen React/Ink terminal app
• Headless commands – traditional factory headless <command> sub-commands powered by Commander

The entry-point (src/index.ts) detects how it was invoked and chooses the right mode automatically.

1. Overview of the Hybrid Architecture

src/
├── index.ts          # Hybrid entry – mode detection
│
├── app.tsx           # React/Ink TUI (interactive mode)
│
└── commands/         # Commander commands (headless mode)
    ├── droid.ts
    └── login.ts

• No positional args ➜ Interactive TUI
• headless subcommand ➜ Headless mode

2 · Local Development

All dev tasks are exposed as npm scripts – never run compiled .js files directly.

Purpose	Command
Start CLI (auto mode)	npm start
Start with Node inspector	npm run debug
Lint source	npm run lint
Type-check	npm run typecheck
Run tests	npm test
Build JS into dist/	npm run build
Produce executable bundle	npm run bundle
Clean build artifacts	npm run clean

The start/debug scripts use tsx so you can edit TypeScript and restart instantly.

3 · Testing Both Modes Locally

Interactive TUI

# Launch interactive UI
npm start

You’ll see a colourful Ink interface; quit with Ctrl-C.

Headless Commands

# Show global help
npm start -- --help

# Show headless subcommands
npm start -- headless --help

# Run login interactively (headless)
npm start -- headless login

# Send message to a droid
npm start -- headless droid "Hello, Droid!" --session-id <sessionId>

The extra -- after npm start passes subsequent flags to the CLI.

4 · Development vs Production

Phase	Command(s)	Result
Dev	npm start / npm run debug	Runs from TS sources with tsx, fast reload.
Build	npm run build	Compiles TS → dist/.
Bundle	npm run bundle (calls build)	Generates single executable bundle/factory.js.
Publish	npm publish (bundled in prepare)	Users install factory binary from npm.

During CI the prepare script produces the bundle automatically.

5 · Examples

Headless examples

# Show authentication status
factory headless status

# Authenticate (opens browser)
factory headless login

# Talk to Droid
factory headless droid "Hello" --session-id dOLpXUI8ux6YdZrg3kCs

Interactive example

# Simply run with no args
factory

6 · Testing the Production factory Command

Sometimes you need to test the exact binary users will get from npm install -g factory-cli.
Follow this workflow:

# 1. Build optimised bundle (also compiles TS → JS)
npm run bundle

# 2. Link globally so `factory` is on your PATH
npm link

# 3. Use it anywhere
factory --help
factory headless status
factory headless droid "Hello" --session-id <sessionId>

# 4. (Optional) Un-link when finished
npm unlink -g factory-cli

Situation	Command to use
Fast iteration / TypeScript	npm start -- <args>
Debug with inspector	npm run debug -- <args>
Validate production bundle	npm run bundle && npm link then factory headless <args>

ℹ️ Tip: The extra -- after npm start or npm run debug passes the remaining flags directly to the CLI.

7 · ESM & Imports

The package is "type": "module"; all runtime imports use .js extensions even though the source is TypeScript. The build pipeline rewrites them automatically.

8 · Troubleshooting

Problem	Fix
EACCES when running factory	Ensure the bundle is executable (chmod +x bundle/factory.js). npm run bundle handles this automatically.
module not found after rename	Run npm run clean && npm run bundle to rebuild from scratch.
Global command still points to old code	Run npm unlink -g factory-cli && npm link to refresh the symlink.

9 · Contributing

• pnpm install (or npm install) at repo root
• cd apps/factory-cli
• Implement feature / fix
• Ensure npm run lint && npm run typecheck && npm test pass
• Commit & open PR 🚀