# Finding the Maka CLI Implementation in the Apache Maka Repository

> Locate the Maka CLI implementation within the apache/maka repository. Find the entry point and core logic in the packages/cli workspace. Discover the exact file paths for quick access.

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

---

**The Maka CLI implementation is located in the `packages/cli` workspace of the apache/maka repository, with its entry point at [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) and core logic in [`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts).**

If you are looking to extend or debug the **Maka CLI implementation**, you will find the entire source tree under the `packages/cli` directory. This workspace contains everything from the thin entry wrapper to the command dispatcher and supporting utilities that power the `maka` executable distributed on npm.

## CLI Entry Point and Workspace Structure

The **Maka CLI** lives within the monorepo's `packages/cli` workspace. When you install the `@maka/cli` package globally or run it via `npx`, the binary points to a tiny wrapper script that bootstraps the full application.

The entry point is **[[`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts)](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts)**. This file serves as the minimal bootstrapper—it imports and immediately invokes `launchMakaCli` from the core module. This separation keeps the executable surface small and delegates all logic to the internal architecture.

## Core Architecture in [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts)

The bulk of the **Maka CLI implementation** resides in **[[`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts)](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts)**. This module defines the command taxonomy, argument parsing, and dispatch logic through several key exports:

- **`MakaCliCommand`** – A TypeScript union type representing all supported sub-commands, including `tui`, `run`, `activate`, `eval`, and `runtime-host` variants.
- **`parseMakaCliArgs`** – The argument parser that maps raw command-line flags to structured `MakaCliCommand` shapes.
- **`runMakaCli`** – The central dispatcher that reads the package version, resolves data roots, and routes validated commands to their specific implementations (such as [`runtime-host-run-command.js`](https://github.com/apache/maka/blob/main/runtime-host-run-command.js) or [`activation-command.js`](https://github.com/apache/maka/blob/main/activation-command.js)).
- **`launchMakaCli`** – The async entry helper used by [`cli.ts`](https://github.com/apache/maka/blob/main/cli.ts) to start the process, execute the dispatch loop, and handle exit codes properly.

## Supporting Modules and Utilities

Several adjacent files in `packages/cli/src/` provide specialized functionality for the CLI:

- **[[`packages/cli/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts)](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts)** – Parses arguments specifically for the `runtime-host` 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)](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli-context.ts)** – Supplies context objects for the TUI runtime-host client.
- **[[`packages/cli/src/cli-ui-locale.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-ui-locale.ts)](https://github.com/apache/maka/blob/main/packages/cli/src/cli-ui-locale.ts)** – Resolves UI locale settings from the environment.
- **[[`packages/cli/src/cli-invocation.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-invocation.ts)](https://github.com/apache/maka/blob/main/packages/cli/src/cli-invocation.ts)** – Provides helpers for invoking sub-commands programmatically from other packages.

## Command Dispatch and Execution Flow

When you execute a `maka` command, the flow follows a strict pipeline defined in the core implementation:

1. **Wrapper Invocation** – [`cli.ts`](https://github.com/apache/maka/blob/main/cli.ts) calls `launchMakaCli`.
2. **Argument Parsing** – `parseMakaCliArgs` normalizes input into a `MakaCliCommand` discriminated union.
3. **Dispatch** – `runMakaCli` matches the command variant and loads the appropriate implementation file (e.g., [`runtime-host-service-command.js`](https://github.com/apache/maka/blob/main/runtime-host-service-command.js) for service management).
4. **Execution** – The specific command handler executes, with utilities like [`cli-ui-locale.ts`](https://github.com/apache/maka/blob/main/cli-ui-locale.ts) providing localization context.

This architecture keeps the core CLI agnostic of specific command implementations while ensuring type safety across the command surface.

## Practical Usage Examples

After installing the package globally with `npm install -g @maka/cli`, you can invoke the following commands that are handled by the implementation described above:

Launch the interactive TUI (default behavior):

```bash
maka

```

Execute a single prompt non-interactively:

```bash
maka run --prompt "Explain quantum entanglement in one sentence"

```

Activate a cloud session with JSONL output:

```bash
maka activate --session-id abc123 --output jsonl

```

Install a Runtime Host service on Linux or macOS:

```bash
maka runtime-host service install --root /var/lib/maka --websocket-port 8080 --json

```

Display help or version information:

```bash
maka --help
maka --version

```

## Summary

- The **Maka CLI implementation** is housed in the `packages/cli` workspace of the apache/maka repository.
- **[`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts)** serves as the thin entry wrapper that delegates to the core.
- **[`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts)** contains the primary logic, including `MakaCliCommand`, `parseMakaCliArgs`, and `runMakaCli`.
- Supporting utilities like [`runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/runtime-host-cli.ts) and [`cli-ui-locale.ts`](https://github.com/apache/maka/blob/main/cli-ui-locale.ts) handle specialized parsing and localization.
- The published `@maka/cli` npm package points its binary to the [`cli.ts`](https://github.com/apache/maka/blob/main/cli.ts) wrapper, making the full implementation available as the `maka` command.

## Frequently Asked Questions

### Where is the main entry point for the Maka CLI?

The main entry point is **[[`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts)](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts)**. This file acts as a minimal bootstrapper that imports `launchMakaCli` from [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts) and starts the asynchronous execution loop.

### What commands are supported by the Maka CLI implementation?

According to the source code in [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts), the CLI supports a union of commands including **`tui`**, **`run`**, **`activate`**, **`eval`**, and various **`runtime-host`** sub-commands. The `MakaCliCommand` type definition enumerates all valid command shapes that the parser recognizes.

### How does the Maka CLI parse command-line arguments?

Argument parsing is handled by the **`parseMakaCliArgs`** function exported from [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts). This function validates raw process arguments and maps them to the structured `MakaCliCommand` union type, which `runMakaCli` then uses to route execution to the appropriate command handler.

### Which npm package contains the Maka CLI binary?

The **`@maka/cli`** package contains the CLI binary. When installed, the package.json bin field points to the compiled output of [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts), allowing you to run the `maka` command directly from your terminal.