Apache Maka TUI/CLI Interface: Complete Developer Guide

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 file serves as the minimal Node.js shebang script:

#!/usr/bin/env node

Located at 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 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	Locale-aware strings for welcome banner, commands, and keybindings
tui-shortcut-copy.ts	Renders platform-specific shortcuts
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, 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:

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:

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

maka runtime-host service update Manages host service updates:

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:

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

maka update and maka uninstall Manage the global installation:

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 — Main command registration
• runtime-host-cli-installation.ts — Install/uninstall operations
• runtime-host-cli-context.ts — Context management
• runtime-host-check-update.ts — Update detection
• runtime-host-reconcile-update.ts — Update application

Installation and First Run

Get started with the Apache Maka CLI via npm:

# 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

# 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	Entry shebang script
packages/cli/src/cli-core.ts	Command parsing and TUI/CLI routing
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	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 delegates to launchMakaCli in cli-core.ts
• TUI rendering relies on 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}