# What Is the CLI Package in Apache Maka?

> Discover the CLI package in Apache Maka. It acts as the front-end entry point, offering an interactive TUI and scriptable command-line interface to orchestrate core subsystems.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-09-10

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-session-status.ts), [`tui-clipboard.ts`](https://github.com/apache/maka/blob/main/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:

```bash

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

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/src/runtime-host-cli.ts) and uses [`src/runtime-host-cli-context.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.