For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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).

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

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:

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:

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.

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.

See also

  • AI UI β€” natural-language sibling using the same command registry

  • MCP Server β€” out-of-process server using the same domain layer

  • Harvest β€” the monorepo @holons/text-ui lives in

Last updated

Was this helpful?