> For the complete documentation index, see [llms.txt](https://docs.holons.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.holons.io/software/text-ui.md).

# Text UI

**`@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

```bash
# 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:

```ts
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](/software/ai-ui.md) **share the same `CommandRegistry` shape**. Each command is a `CoreCommand`:

```ts
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`](/software/mcp-server.md)),
* 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](/software/ai-ui.md). For external clients (Claude Desktop, IDEs), use the [MCP server](/software/mcp-server.md). For day-to-day community use, use the [Telegram bot](/software/holonsbot.md) or the [web dashboard](/software/harvest-dashboard.md).

## See also

* [AI UI](/software/ai-ui.md) — natural-language sibling using the same command registry
* [MCP Server](/software/mcp-server.md) — out-of-process server using the same domain layer
* [Harvest](/software/harvest-dashboard.md) — the monorepo `@holons/text-ui` lives in


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.holons.io/software/text-ui.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.