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

> Learn to interact with your projects using Maka's TUI/CLI. This guide shows you how to leverage Maka for seamless command-line and interactive terminal UI operations.

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

---

**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`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts), which serves as a minimal wrapper that delegates to `launchMakaCli` ([source](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts#L21‑L24)). 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`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts) ([source](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts#L96‑L107)). 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`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts) ([source](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts#L55‑L71)).

### Default TUI Behavior

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

```bash
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`](https://github.com/apache/maka/blob/main/packages/cli/src/workspace-root.ts) ([source](https://github.com/apache/maka/blob/main/packages/cli/src/workspace-root.ts#L1‑L30)), then builds the TUI context via `runRuntimeHostTui` ([source](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts#L44‑L56)).

### Resuming Previous Sessions

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

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

```

The `parseTuiArgs` function handles these flags in [`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts) ([source](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts#L59‑L99)), 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`:

```bash
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`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-tui-command.ts) creates a session store and handles host connection conflicts interactively ([source](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-tui-command.ts#L24‑L44)).

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

```bash
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:

```bash
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:

```bash
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`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts) ([source](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts#L55‑L71)) 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-tui-command.ts) ([source](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-tui-command.ts#L51‑L57)) 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](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-tui-command.ts#L51‑L75)).

## 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`](https://github.com/apache/maka/blob/main/cli.ts)), argument parsing ([`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts)), data resolution ([`workspace-root.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.