# How to Run the Apache Maka TUI or a One-Shot Turn from Source

> Learn to run the Apache Maka TUI or a one-shot turn from source. Clone the repo, install dependencies, build the CLI, and execute for interactive use or single commands.

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

---

**Clone the Apache Maka repository, run `npm install` and `npm run build` to compile [`packages/cli/dist/cli.js`](https://github.com/apache/maka/blob/main/packages/cli/dist/cli.js), then execute the binary without arguments to launch the interactive terminal UI or append `run "your prompt"` for a single non-interactive turn.**

When working with the Apache Maka project, developers often need to test changes by running the terminal UI (TUI) directly from a source checkout rather than using a published package. This guide explains how to build the CLI from source and launch both interactive sessions and automated one-shot turns using the repository's TypeScript build pipeline and the `runMakaPiTui` entry point.

## Prerequisites and Repository Setup

Before building, ensure you have Node.js and npm installed. The Maka repository uses npm workspaces to manage the `@maka/*` sub-packages.

Clone the repository and install dependencies:

```bash
git clone https://github.com/apache/maka.git
cd maka
npm install

```

The root [`package.json`](https://github.com/apache/maka/blob/main/package.json) defines the workspace layout, pulling in all sub-packages including the CLI, Runtime Host, and shared libraries into the local node_modules.

## Building the CLI from Source

The CLI package requires TypeScript compilation before execution. The build process compiles `packages/cli/src/` into the executable [`packages/cli/dist/cli.js`](https://github.com/apache/maka/blob/main/packages/cli/dist/cli.js).

Run the build command:

```bash
npm run build

```

Alternatively, for a more granular approach that builds workspace dependencies first:

```bash
npm run build:workspace-deps
npm run build

```

According to the source code in **[`packages/cli/package.json`](https://github.com/apache/maka/blob/main/packages/cli/package.json)**, the build script executes `tsc -p tsconfig.json`, generating the JavaScript bundle. This [`dist/cli.js`](https://github.com/apache/maka/blob/main/dist/cli.js) file serves as the `bin` entry point for both interactive and non-interactive modes.

## Launching the Interactive TUI

To start the interactive terminal UI, execute the compiled binary without arguments:

```bash
node packages/cli/dist/cli.js

```

This command invokes **`runMakaPiTui`**, defined in **[`packages/cli/src/pi-tui-runner.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/pi-tui-runner.ts)** (lines 49-51). The function signature accepts a `MakaPiTuiInput` object and creates a `TuiMainScreen` renderer, wiring it to a `MakaSessionDriver` that communicates with the local Runtime Host to process conversation turns.

### Exiting the TUI

Terminate the session by pressing **Ctrl-C** or typing the `!exit` command. The source code handles cleanup through **`handleSigint`** and **`handleSigterm`** functions located in **[`packages/cli/src/pi-tui-runner.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/pi-tui-runner.ts)** (lines 86-92), ensuring proper resource disposal and graceful shutdown when the process exits.

## Executing a One-Shot Turn

For automated workflows or single queries without launching the full interface, use the `run` sub-command followed by your prompt string:

```bash
node packages/cli/dist/cli.js run "Summarize the project architecture and list risks"

```

### How the Run Command Works

The CLI argument parsing logic resides in **[`packages/cli/src/cli-command-parser.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-command-parser.ts)**. When the parser detects the `run` sub-command, it constructs a **`MakaPiTuiInput`** object (defined in **[`packages/cli/src/pi-tui-contracts.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/pi-tui-contracts.ts)**) with **`resumeSessionId`** set to `undefined` and passes it to `runMakaPiTui`.

Unlike the interactive mode, this configuration skips the `TuiMainScreen` initialization. The driver submits the message via **`input.driver.submitMessage`** (as implemented around lines 1264-1272), prints the resulting output to stdout, and terminates the process immediately without rendering the terminal interface.

### Using npx for Local Execution

If you prefer not to invoke Node directly with paths, you can use npx with the local package:

```bash
npx --yes --package file:packages/cli muka run "Explain the architecture"

```

This approach references the freshly built package without requiring a global installation or manual path specification.

## Summary

- **Source checkout**: Clone from GitHub and run `npm install` to populate workspace dependencies defined in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json).
- **Build process**: Execute `npm run build` to generate [`packages/cli/dist/cli.js`](https://github.com/apache/maka/blob/main/packages/cli/dist/cli.js) via the TypeScript compiler (`tsc -p tsconfig.json`).
- **Interactive TUI**: Run `node packages/cli/dist/cli.js` to launch the terminal interface managed by `runMakaPiTui` in [`pi-tui-runner.ts`](https://github.com/apache/maka/blob/main/pi-tui-runner.ts).
- **One-shot execution**: Append `run "prompt"` to execute a single turn without UI initialization, using the same `MakaSessionDriver` infrastructure but with immediate termination after the response.
- **Process cleanup**: Use **Ctrl-C** or `!exit` to trigger the signal handlers in [`pi-tui-runner.ts`](https://github.com/apache/maka/blob/main/pi-tui-runner.ts) for graceful shutdown.

## Frequently Asked Questions

### What is the difference between the TUI and a one-shot turn?

The TUI (Terminal User Interface) launches an interactive `TuiMainScreen` session where you can conduct multiple turns with real-time visual feedback. A one-shot turn uses the same `MakaSessionDriver` and Runtime Host infrastructure but submits a single prompt via `input.driver.submitMessage` and exits immediately without rendering the interface or waiting for further user input.

### Where is the CLI entry point defined in the source code?

The executable entry point is declared in **[`packages/cli/package.json`](https://github.com/apache/maka/blob/main/packages/cli/package.json)** under the `bin` field, pointing to [`dist/cli.js`](https://github.com/apache/maka/blob/main/dist/cli.js). The main orchestration logic for booting the TUI lives in **[`packages/cli/src/pi-tui-runner.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/pi-tui-runner.ts)**, specifically the `runMakaPiTui` function exported at lines 49-51, which initializes the session driver and UI components.

### How do I exit the Maka TUI cleanly?

Press **Ctrl-C** or type `!exit` to trigger the cleanup handlers. The **`handleSigint`** and **`handleSigterm`** functions in **[`packages/cli/src/pi-tui-runner.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/pi-tui-runner.ts)** (lines 86-92) manage process termination and ensure the Runtime Host connections are properly closed.

### Can I run the CLI without building the project first?

No. The source is written in TypeScript and must be compiled to JavaScript before Node.js can execute it. The build step, executed via `npm run build` using `tsc -p tsconfig.json` as configured in the CLI package, generates the required [`dist/cli.js`](https://github.com/apache/maka/blob/main/dist/cli.js) file that serves as the runtime entry point.