How to Use Maka’s TUI/CLI for Project Interaction

Maka provides a unified command-line interface that launches an interactive terminal UI by default or executes non-interactive commands when specific subcommands or flags are provided.

The Apache Maka project delivers a sophisticated runtime environment for AI-assisted development through its TypeScript-based CLI package. Understanding how to leverage both the interactive TUI and headless command modes allows developers to seamlessly manage projects, resume sessions, and execute model turns. This guide explores the implementation details found in the apache/maka repository to help you maximize productivity with the Maka CLI.

Getting Started with the Maka CLI

The Maka CLI entry point resides in packages/cli/src/cli.ts, which serves as a minimal wrapper that delegates to launchMakaCli (source). This architecture keeps the entry script clean while centralizing logic in the core module.

When you invoke the maka command, the system immediately calls runMakaCli in packages/cli/src/cli-core.ts (source). This function orchestrates the entire execution flow by reading package versions, parsing arguments, resolving data roots, and dispatching to the appropriate handler.

Launching the Interactive TUI

By default, Maka assumes you want the interactive experience. When no arguments are supplied, the parser automatically sets kind: 'tui' via parseMakaCliArgs in packages/cli/src/cli-core.ts (source).

Default TUI Behavior

Running Maka without arguments launches the terminal interface in the current working directory:

maka

This command triggers the full TUI initialization sequence. The system first resolves data roots through deriveMakaDataRoots and resolveMakaDataRoots defined in packages/cli/src/workspace-root.ts (source), then builds the TUI context via runRuntimeHostTui (source).

Resuming Previous Sessions

Use the --resume flag to reconnect to an existing session, optionally combined with --cwd to change the working directory:

maka --resume 12345
maka --resume 12345 --cwd /path/to/project

The parseTuiArgs function handles these flags in packages/cli/src/cli-core.ts (source), ensuring the TUI restores your previous context including turn history and active goals.

Connecting to Remote Runtime Hosts

For distributed workflows, connect the TUI to a specific Runtime Host profile using the --host flag, and select a project with --project:

maka --host my-remote-profile
maka --host my-remote-profile --project project-id

According to the source code, runRuntimeHostTui in packages/cli/src/runtime-host-tui-command.ts creates a session store and handles host connection conflicts interactively (source).

Executing Non-Interactive Commands

Maka supports headless execution for automation and scripting scenarios. When you provide specific subcommands, the CLI bypasses the TUI and returns control immediately after completion.

Running Single Model Turns

Execute a single turn without entering the interactive interface using the run subcommand:

maka run echo "Hello, world!"

This mode skips the UI rendering components found in packages/ui/src/ and executes the model directly through the Runtime Host client.

Activating Cloud Sessions

For cloud-based ephemeral compute, use the activate command with appropriate flags:

maka activate --some-flag value

This streams JSONL output suitable for piping to other tools or logging systems.

Running Declarative Experiments

Execute structured experiments defined in YAML configuration files:

maka eval my-experiment.yaml

The eval subcommand processes the experiment definition and reports results without requiring TUI interaction.

Core Architecture and Data Flow

Understanding the internal pipeline helps troubleshoot connection issues and optimize workflow integration.

Argument Parsing and Dispatch

The parseMakaCliArgs function in packages/cli/src/cli-core.ts (source) analyzes process.argv to determine execution mode. Key flags include:

• --resume: Session ID to restore
• --cwd: Working directory override
• --host: Target Runtime Host profile
• --project: Specific project ID on the host
• --version: Displays version from readPackageVersion

Workspace and Data Root Resolution

Before launching any interface, Maka resolves filesystem paths through packages/cli/src/workspace-root.ts. The system distinguishes between the workspace root (your project files) and the client data root (Maka's internal state and caches), mapping profile names to appropriate directories.

TUI Session Management

The runRuntimeHostTui function in packages/cli/src/runtime-host-tui-command.ts (source) performs three critical tasks:

1. Creates a session store to maintain state
2. Builds the TUI context including conflict handling mechanisms
3. Invokes runMakaPiTui to start the rendering loop

First-run onboarding logic guides users through initial Runtime Host setup when no previous configuration exists (source).

Summary

• Default behavior: Running maka without arguments launches the interactive TUI via runRuntimeHostTui
• Session persistence: Use --resume with a session ID to restore previous context
• Remote workflows: Combine --host and --project flags to connect to specific Runtime Host profiles
• Non-interactive modes: Use maka run, maka activate, or maka eval for scripting and automation
• Architecture: The CLI separates concerns between entry points (cli.ts), argument parsing (cli-core.ts), data resolution (workspace-root.ts), and UI rendering (packages/ui/src/)

Frequently Asked Questions

How do I switch between different Runtime Host profiles in the Maka TUI?

Pass the --host flag followed by your profile name when launching Maka. The system resolves the connection details through runtime-host-cli-context.ts and establishes the session before rendering the interface. If the specified host is unreachable, the TUI displays a conflict prompt allowing you to retry or select an alternative.

Can I use the Maka CLI in CI/CD pipelines without the interactive interface?

Yes. Use the run, activate, or eval subcommands depending on your use case. These modes execute through runMakaCli without invoking the TUI rendering components, returning exit codes and JSONL output suitable for automated testing and deployment workflows.

What happens if I specify both a session resume and a working directory change?

The CLI processes both flags sequentially. When you execute maka --resume 12345 --cwd /new/path, the system first restores session 12345, then switches the working directory to /new/path. This allows you to resume a session in the context of a different codebase or subdirectory without losing your conversation history.

Where does Maka store configuration and session data?

Data roots are determined by deriveMakaDataRoots in packages/cli/src/workspace-root.ts. The system separates runtime data (session history, model cache) from workspace data (your project files), storing client data in a profile-specific directory typically located in your user home or as specified by environment variables.

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