Finding the Maka CLI Implementation in the Apache Maka Repository

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 and core logic in 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). 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

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). 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 or activation-command.js).
• launchMakaCli – The async entry helper used by 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) – 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) – 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) – 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) – 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 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 for service management).
4. Execution – The specific command handler executes, with utilities like 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):

maka

Execute a single prompt non-interactively:

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

Activate a cloud session with JSONL output:

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

Install a Runtime Host service on Linux or macOS:

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

Display help or version information:

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 serves as the thin entry wrapper that delegates to the core.
• packages/cli/src/cli-core.ts contains the primary logic, including MakaCliCommand, parseMakaCliArgs, and runMakaCli.
• Supporting utilities like runtime-host-cli.ts and cli-ui-locale.ts handle specialized parsing and localization.
• The published @maka/cli npm package points its binary to the 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). This file acts as a minimal bootstrapper that imports launchMakaCli from 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, 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. 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, allowing you to run the maka command directly from your terminal.

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