What Is the CLI Package in Apache Maka?

The cli package serves as the front‑end entry point for Apache Maka, exposing both an interactive Text‑User‑Interface (TUI) and a scriptable command‑line interface that bootstraps the Runtime Host and orchestrates core subsystems.

The cli package transforms Maka’s underlying runtime‑host architecture into a usable command‑line tool. Located in packages/cli/, this module supplies the public maka binary that users invoke from their terminal. It functions as the primary interface between human operators (and automation scripts) and Maka’s execution engine.

Core Responsibilities of the CLI Package

Terminal Interface and Command Dispatch

The package bundles both a rich Text‑User‑Interface (TUI) for interactive sessions and simple command‑line operations. According to the packages/cli/README.md, the CLI supports workflows such as maka run … for one‑off turns and maka doctor for diagnostics. The dispatcher logic resides in packages/cli/src/run-command-core.ts, which routes top‑level arguments to the appropriate handlers.

Runtime Host Bootstrap and Control

The cli package contains the logic that starts, configures, and communicates with the Runtime Host—the single authority that executes model turns. In packages/cli/src/runtime-host-cli.ts (lines 56‑84), the full set of runtime‑host sub‑commands is defined, including runtime-host serve, runtime-host setup, and runtime-host service …. This file acts as the control plane for the Runtime Host lifecycle.

Subsystem Integration

Rather than implementing core algorithms, the package wires together supporting libraries. The package.json (lines 8‑10) declares dependencies on the core, storage, MCP, runtime, eval, and runtime‑host libraries. This architecture keeps the binary footprint minimal while presenting a coherent command surface that aggregates functionality from across the monorepo.

Profile and Connection State Management

Helper functions in packages/cli/src/runtime-host-cli-context.ts (lines 20‑38) manage local state. These utilities read the user’s profile, establish a Runtime Host connection, and handle peer‑to‑peer setups. This ensures that every command execution begins with the correct environmental context and active connection parameters.

Key Source Files in the CLI Package

The following files constitute the backbone of the package’s functionality:

• packages/cli/package.json – Declares the maka binary entry point and lists all runtime‑host dependencies required for operation.
• packages/cli/src/runtime-host-cli.ts – Defines the complete command tree for Runtime Host operations, including setup and service management sub‑commands.
• packages/cli/src/runtime-host-cli-context.ts – Handles connection initialization, profile loading, and peer client creation for distributed setups.
• packages/cli/src/run-command-core.ts – Core dispatcher that processes top‑level CLI arguments such as run and doctor.
• packages/cli/src/tui-session-status.ts, tui-clipboard.ts, etc. – Implement the interactive terminal UI components used during live sessions.

Using the Maka CLI

The following examples demonstrate how the cli package functions in practice:

# Display the full help screen generated by the cli package

maka --help

# Execute a single turn without entering the interactive TUI

maka run "Summarize the project's architecture"

# Launch the interactive terminal UI

maka

For programmatic usage, the same core dispatcher that powers the binary can be imported directly:

// Minimal programmatic invocation using the CLI package internals
import { runCommandCore } from '@maka/cli/src/run-command-core.js';

await runCommandCore(['run', 'Explain the purpose of the CLI package']);

Summary

• The cli package provides the public maka command and serves as the primary user interface for the Apache Maka ecosystem.
• It exposes both an interactive TUI and a scriptable, non‑interactive CLI for automation.
• It bootstraps and controls the Runtime Host through dedicated command modules in runtime-host-cli.ts.
• It aggregates functionality from core subsystems (storage, MCP, eval) while maintaining a minimal binary footprint.
• It manages local configuration, profiles, and peer‑to‑peer connections via runtime-host-cli-context.ts.

Frequently Asked Questions

What commands does the Maka CLI provide?

The CLI provides top‑level commands such as maka run for executing single turns, maka doctor for system diagnostics, and maka (no arguments) to launch the interactive TUI. It also exposes a full suite of runtime-host sub‑commands for managing the execution backend.

How does the CLI package interact with the Runtime Host?

The package acts as the control plane. It defines all Runtime Host sub‑commands in src/runtime-host-cli.ts and uses src/runtime-host-cli-context.ts to establish connections, read profiles, and initialize the host process before dispatching work.

Can I use the CLI package programmatically?

Yes. The runCommandCore function exported from src/run-command-core.ts can be imported and invoked programmatically, accepting an array of command arguments identical to those passed via the terminal.

Where is the maka binary defined?

The binary entry point is declared in packages/cli/package.json (lines 8‑10), which specifies the executable script that Node.js invokes when users run the maka command from their shell.

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