# Apache Maka TUI/CLI Interface: Complete Developer Guide

> Explore the Apache Maka TUI/CLI interface, a single binary for interactive terminal UI or direct command execution. Get started with Maka today.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: developer-guide
- Published: 2026-08-29

---

**The Apache Maka TUI/CLI interface is a single `maka` binary that launches an interactive Terminal UI when run without arguments, or executes commands directly when invoked with sub-commands like `maka run "prompt"`.**

The **Apache Maka command-line interface** ships as the `maka-agent` npm package and provides a unified entry point for both visual interaction and headless automation. This article breaks down the architecture, key source files, and practical usage patterns based on the official Apache Maka repository.

## Architecture of the Maka CLI

The interface follows a three-layer design that cleanly separates entry, routing, and rendering concerns.

### Layer 1: Entry Point

The **[`cli.ts`](https://github.com/apache/maka/blob/main/cli.ts)** file serves as the minimal Node.js shebang script:

```bash
#!/usr/bin/env node

```

Located at [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts), this file imports `launchMakaCli` and passes a static launch-options object to bootstrap the system.

### Layer 2: CLI Core Dispatcher

The **[`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts)** module contains `launchMakaCli`, which:
- Builds a yargs-style command tree
- Decides whether to start the **TUI** (interactive) or execute a **CLI sub-command** (non-interactive)
- Wires up Runtime Host services

This decision happens at runtime based on whether arguments were provided beyond the binary name.

### Layer 3: TUI Rendering

All interactive visual elements are handled by `tui-*.ts` modules in `packages/cli/src/`:

| Module | Purpose |
|--------|---------|
| [`tui-primary-guidance.ts`](https://github.com/apache/maka/blob/main/tui-primary-guidance.ts) | Locale-aware strings for welcome banner, commands, and keybindings |
| [`tui-shortcut-copy.ts`](https://github.com/apache/maka/blob/main/tui-shortcut-copy.ts) | Renders platform-specific shortcuts |
| [`tui-session-status.ts`](https://github.com/apache/maka/blob/main/tui-session-status.ts) | Session state visual indicators |

## The Interactive TUI Experience

Running `maka` without arguments drops you into the **Terminal UI** with three primary components:

### Welcome Banner

Sourced from `getTuiPrimaryGuidance(locale, platform)` in [`tui-primary-guidance.ts`](https://github.com/apache/maka/blob/main/tui-primary-guidance.ts), the banner displays:
- Tagline: "Get things done together"
- Quick-start prompts for conversations and session switching

### Command Reference Table

The TUI renders a scrollable list of slash commands:

| Command | Purpose |
|---------|---------|
| `/compact` | Compress conversation history |
| `/context` | Manage conversation context |
| `/exit` | Quit the TUI |
| `/graph` | Visualize agent execution graph |
| `/mcp` | Model Context Protocol operations |
| `/skill` | Invoke registered skills |

### Platform-Aware Keybindings

The `renderTuiShortcutCopy` helper adapts shortcuts to your OS:

- **Ctrl+O** — Open file picker
- **Ctrl+T** — New session tab
- **Alt+Enter** — Submit multi-line input

All strings support **zh** (Chinese) and **en** (English) locales.

## The Non-Interactive CLI Mode

When invoked with sub-commands, `maka` operates as a traditional CLI for automation and scripting.

### Essential Commands

**`maka run "<prompt>"`**
Executes a single turn in headless mode, returning output to stdout:

```bash
maka run "Summarize this repository's architecture"

```

**`maka runtime-host setup`**
Installs a persistent Runtime Host service on Linux/macOS, or launches a temporary host on Windows:

```bash
maka runtime-host setup \
    --principal my-client \
    --preset terminal-client

```

**`maka runtime-host service update`**
Manages host service updates:

```bash
maka runtime-host service check-update --target next --json
maka runtime-host service update-policy --target latest

```

**`maka eval run`**
Runs declarative experiments using the bundled Eval runtime:

```bash
maka eval run harbor-experiment.json --out .maka-eval/run-001

```

**`maka update` and `maka uninstall`**
Manage the global installation:

```bash
maka update --target next
npm uninstall --global maka-agent

```

### Runtime Host Sub-Command Family

The `runtime-host-*.ts` files implement extensive service management:

- [`runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/runtime-host-cli.ts) — Main command registration
- [`runtime-host-cli-installation.ts`](https://github.com/apache/maka/blob/main/runtime-host-cli-installation.ts) — Install/uninstall operations
- [`runtime-host-cli-context.ts`](https://github.com/apache/maka/blob/main/runtime-host-cli-context.ts) — Context management
- [`runtime-host-check-update.ts`](https://github.com/apache/maka/blob/main/runtime-host-check-update.ts) — Update detection
- [`runtime-host-reconcile-update.ts`](https://github.com/apache/maka/blob/main/runtime-host-reconcile-update.ts) — Update application

## Installation and First Run

Get started with the Apache Maka CLI via npm:

```bash

# Install beta version globally

npm install --global maka-agent@next

# Verify installation

maka --version
maka --help

# Launch interactive TUI

cd /path/to/project
maka

```

## Complete Usage Examples

```bash

# Interactive mode — explore via TUI

maka

# Headless single query

maka run "Generate unit tests for src/utils.ts"

# Persistent host setup for CI/CD

npx --yes --package maka-agent@next \
    maka runtime-host setup \
    --principal ci-runner \
    --preset headless

# Check service status programmatically

maka runtime-host service check-update --json | jq '.available'

# Run evaluation suite

maka eval run pier-experiment.json --out ./results/$(date +%Y%m%d)

```

## Key Implementation Files

| File Path | Role |
|-----------|------|
| [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) | Entry shebang script |
| [`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts) | Command parsing and TUI/CLI routing |
| [`packages/cli/src/tui-primary-guidance.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-primary-guidance.ts) | Localized UI strings and guidance |
| `packages/cli/src/tui-*.ts` | Rendering primitives and helpers |
| `packages/cli/src/runtime-host-cli*.ts` | Runtime Host command implementations |
| [`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md) | Official documentation and quickstart |

## Summary

- The **Apache Maka TUI/CLI** is a single binary with dual-mode operation: interactive TUI when called bare, command executor when passed arguments
- **Entry point** at [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) delegates to `launchMakaCli` in [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts)
- **TUI rendering** relies on [`tui-primary-guidance.ts`](https://github.com/apache/maka/blob/main/tui-primary-guidance.ts) for content and `tui-*.ts` modules for presentation
- **All sub-commands** live in dedicated modules under `packages/cli/src/`, with the `runtime-host` family being the most extensive
- **Localization** supports `zh` and `en` with platform-aware keybinding display

## Frequently Asked Questions

### How do I switch between TUI and CLI mode in Apache Maka?

Run `maka` with no arguments to enter **TUI mode**, or append any sub-command like `maka run "query"` for **CLI mode**. The `launchMakaCli` function in [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts) automatically detects this based on `process.argv` length and routes accordingly—no flags required.

### Can I use Apache Maka in CI/CD pipelines without the interactive UI?

Yes. Use `maka run "<prompt>"` for single-turn execution, or `maka eval run <spec.json>` for structured experiments. Both return results to stdout and exit with appropriate codes. The `runtime-host setup` command also supports headless presets for persistent service deployment.

### Where are the TUI strings and keybindings defined?

All UI text lives in [`packages/cli/src/tui-primary-guidance.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-primary-guidance.ts), exported via `getTuiPrimaryGuidance(locale, platform)`. This includes the welcome tagline, available commands table, and platform-specific shortcut descriptions. Rendering helpers in sibling `tui-*.ts` files convert these strings to terminal markup.