Text UI

Framework-agnostic CLI and REPL for driving holons from the terminal

@holons/text-ui is the command-line interface to the Holons ecosystem. It is the simplest possible renderer for @holons/core/commands: a parser, a dispatcher, and a default text renderer. No framework, no UI library, no network calls beyond what the core commands themselves do.

It's the right tool when you want to:

poke at a holon from a terminal without launching Telegram or a browser,
script repetitive holon operations in shell or CI,
prototype a new core command and exercise it before wiring up a richer UI,
fall back to a working interface when more elaborate UIs aren't an option.

What it is

Name: @holons/text-ui
Location: harvest/packages/text-ui/
Binary: holons
Dependencies: just @holons/core (no SDKs, no frameworks)

Modes

# REPL — interactive shell
holons

# Single command
holons createTask --holonId=garden --title="water seedlings"

# Help
holons --help
holons createTask --help

The REPL prompt:

holons REPL — type "help" or a command, "exit" to quit
holons> createTask --holonId=garden --title="water seedlings"
✓ Task "water seedlings" created in garden
holons> exit

help, exit, and quit are recognized as REPL meta-commands. Everything else is parsed and dispatched through the same registry the AI UI uses.

The argument grammar

A small, predictable grammar. The parser handles both process.argv token arrays and free-form REPL lines (with quote handling).

<command> [--key=value] [--key value] [--flag] [--no-flag] [positional...]

Rules:

--key=value — explicit assignment.
--key value — lookahead form; works if the next token isn't another flag.
--flag — boolean true.
--no-flag — boolean false.
Bare tokens become positional arguments (collected separately from named params).
Single and double quotes group whitespace into one token: --title="water the seedlings".

Values are auto-coerced: true/false → booleans, numeric strings → numbers, everything else stays a string.

How a command dispatches

argv / line
    │
    ▼
parseArgv / parseLine
    │
    ▼
ParsedCommand { command, params, positional }
    │
    ▼
registry.get(command)         ← @holons/core/commands
    │
    ▼
Missing required params? → render help, exit 1
    │
    ▼
command.execute(params)
    │
    ▼
renderer.render(result)

The dispatcher checks for --help, validates required params, calls execute(), and hands the result to a Renderer. Exit code is 0 on success (result.ok === true), 1 on failure.

Renderers

defaultRenderer writes plain text to stdout. The Renderer interface is small:

interface Renderer {
  render(result: CommandResult): void;
  error(err: unknown): void;
}

This is intentionally pluggable. A future structured-output renderer (--json) or a colored renderer for richer terminals would slot in here without changing parsers or dispatchers.

The shared command registry

The text-ui and AI UI share the same CommandRegistry shape. Each command is a CoreCommand:

interface CoreCommand {
  name: string;
  description: string;
  params: { name; type: 'string' | 'number' | 'boolean'; description; required? }[];
  execute(params): Promise<{ ok; message?; data? }>;
}

A command authored once is automatically:

a CLI subcommand (holons <name> --param=value),
a Claude tool (auto-generated JSON Schema from params),
a candidate MCP tool (via the commands domain of @holons/mcp-ui),
discoverable through the central commands domain of @holons/core.

This is the leverage of the shared-core architecture: writing a new command is one file, and four interfaces light up.

Help system

Help is generated from the registry — there is no separate "help text" to maintain.

holons --help              → lists all commands with descriptions
holons createTask --help   → lists params, types, required flags

The width-aligned formatting in cli.ts makes the output readable without bringing in a help-text library.

When to use it

You're authoring a new command and want the fastest possible feedback loop.
You're shell-scripting a holon operation (cron jobs, CI, deployment hooks).
You're testing end-to-end without wanting to spin up the web app.
You want a clean fallback that depends only on @holons/core.

For natural-language input, use the AI UI. For external clients (Claude Desktop, IDEs), use the MCP server. For day-to-day community use, use the Telegram bot or the web dashboard.