# Mako CLI Modes of Operation: Complete Guide to 14 Command Patterns

> Explore Mako CLI modes of operation: interactive TUI, single-shot execution, ACP protocol server, Runtime Host, credential management, profiles, and utilities. Master 14 command patterns.

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

---

**Mako's CLI operates through seven core mode categories: interactive TUI, single-shot execution (run/activate/eval), ACP protocol server, Runtime Host service management, credential management, profile handling, and utility commands.**

The Apache Mako project provides a versatile command-line interface built around a single entry point in [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts). This article examines all operational modes as implemented in [`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts), where the central dispatcher routes commands through type-safe `MakaCliCommand` parsing.

## Interactive TUI Mode

The **Terminal UI** serves as Mako's default mode when invoked without arguments.

### Basic TUI Launch

```bash

# Start fresh interactive session

maka

# Restore previous session by ID

maka --resume abc123

```

The TUI mode triggers through the `tui` case in the dispatcher switch statement (lines 424-444 in [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts)). Argument parsing occurs via `parseTuiArgs` (lines 47-100), which handles session restoration, locale selection, and UI theming options.

### TUI Implementation Details

- Entry point: `parseMakaCliArgs` → `MakaCliCommand` type (lines 35-50)
- Dispatch target: `tui` case handler
- Session persistence: Stored IDs retrievable via `--resume <id>`

## Single-Shot Execution Modes

Three modes execute discrete tasks without entering the interactive UI.

### Run Mode

```bash

# Execute single model turn with text output

maka run --model gpt-4 --prompt "Explain quantum entanglement"

# Shorthand with prompt flag

maka -p "Summarize this document" --model claude-3-opus

```

The `run` case (lines 80-85) invokes `runMakaCli` for non-interactive inference. This mode supports model selection, system prompts, and output formatting flags.

### Activate Mode

```bash

# Activate cloud session and stream JSONL

maka activate --session my-session-id

```

**Activate mode** triggers Cloud Session activation with streaming JSONL output (lines 92-95). This differs from `run` by establishing persistent cloud connections rather than stateless inference.

### Eval Mode

```bash

# Run declarative multi-arm experiment

maka eval experiment.yaml

```

The `eval` case (lines 96-101) loads experiments through the `@maka/eval` package. This mode supports A/B testing, benchmark suites, and reproducible evaluation pipelines.

## ACP Protocol Mode

The **Agent Capability Provider** mode implements the ACP v1 protocol over stdio.

```bash

# Start stdio server for ACP protocol

maka --acp

```

This lightweight server mode (lines 302-309) handles initialization, session creation, and session listing per the ACP specification. Unlike the TUI, this mode operates headless for IDE integrations and external tooling.

## Runtime Host Service Modes

The most extensive mode category manages self-hosted Mako Runtime instances.

### Service Hosting

```bash

# Start WebSocket Runtime Host (default)

maka runtime-host serve --websocket-port 8080

# Direct peer connection mode

maka runtime-host serve --direct-peer

# Managed deployment target

maka runtime-host serve --managed

```

The `runtime-host-serve` case (lines 110-129) launches long-running services supporting three transport modes: WebSocket, direct peer-to-peer, or managed cloud deployment.

### Update Management

```bash

# Update globally installed CLI and Runtime Host

maka update --target latest

# Bootstrap new installation

maka runtime-host installed-update --bootstrap

# Apply pending update

maka runtime-host local-update-apply

# Activate updated version

maka runtime-host local-update-activate

```

Multiple `runtime-host-*` cases (lines 138-192) handle the update lifecycle: bootstrap, apply, and activate operations for locally installed instances.

### Access Credential Management

```bash

# Issue new credential for desktop client

maka runtime-host access issue --principal client1 --preset desktop-client

# List active credentials

maka runtime-host access list

# Revoke specific credential

maka runtime-host access revoke --principal client1

# Generate connection code

maka runtime-host access code

```

The `runtime-host-access-issue` and related cases (lines 165-179) implement OAuth2-style credential flows for client authentication.

### Project Management

```bash

# List remotely available projects

maka runtime-host project list

# Add project to host catalog

maka runtime-host project add --source git+https://github.com/org/project

```

Project commands (lines 272-279) configure which projects a Runtime Host can serve to connected clients.

### Plugin Lifecycle

```bash

# Install host-side plugin

maka runtime-host plugin install --name @maka/plugin-name

# Check plugin status

maka runtime-host plugin status

# Reload without restart

maka runtime-host plugin reload

# Remove plugin

maka runtime-host plugin uninstall --name @maka/plugin-name

```

The `runtime-host-plugin` case (lines 240-251) manages hot-reloadable extensions to the Runtime Host.

### Capability Provider Serving

```bash

# Expose capability provider over WebSocket

maka runtime-host capability-provider serve --port 9000

```

This mode (lines 254-260) differs from `--acp` by using WebSocket transport rather than stdio, enabling browser-based clients.

### Profile Management

```bash

# List all connection profiles

maka runtime-host profile list

# Create or update profile

maka runtime-host profile set --name production --host wss://mako.example.com

# Remove profile

maka runtime-host profile remove --name staging

```

Profile commands (lines 284-306) manage multiple Runtime Host endpoints with stored connection configurations.

## Utility Modes

### Help and Version

```bash

# Display full help text

maka --help
maka -h

# Show version information

maka --version
maka -v

```

The `help` and `version` cases (lines 414-421) provide standard CLI introspection capabilities.

### Error Handling

Invalid arguments trigger the `error` case (lines 426-433), emitting diagnostic messages and optionally redisplaying help text.

## Architecture Summary

Mako's CLI implementation follows a centralized dispatch pattern:

| Component | Location | Responsibility |
|-----------|----------|--------------|
| Entry wrapper | [`packages/cli/src/cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts) | Bootstraps `launchMakaCli` |
| Core dispatcher | [`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts) | Parses arguments, routes to mode handlers |
| Type definitions | [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts) lines 35-50 | `MakaCliCommand` union type |
| Mode implementations | Various `runtime-host-*.ts` files | Sub-command execution logic |
| Locale resolution | [`packages/cli/src/cli-ui-locale.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-ui-locale.ts) | TUI internationalization |

The switch-based dispatcher starting at line 63 enables exhaustive pattern matching across all 14 operational modes, with TypeScript ensuring each `MakaCliCommand` variant receives appropriate handling.

## Summary

- **TUI mode** provides the default interactive experience with session persistence
- **Single-shot modes** (`run`, `activate`, `eval`) execute discrete tasks without UI overhead
- **ACP mode** enables stdio protocol compliance for external tooling integration
- **Runtime Host modes** comprise the largest category: service hosting, updates, access control, projects, plugins, capability providers, and profiles
- **Utility modes** handle help, version, and error display
- All modes route through `parseMakaCliArgs` and the central switch dispatcher in [`cli-core.ts`](https://github.com/apache/maka/blob/main/cli-core.ts)

## Frequently Asked Questions

### What is the default mode when running `maka` with no arguments?

The **TUI (Terminal UI) mode** activates by default. In [`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts), the argument parser detects zero arguments and returns a `tui` command variant, which the dispatcher routes to the interactive interface handler (lines 424-444). This design prioritizes discoverability for new users while maintaining scriptability through explicit flags.

### How does the ACP mode differ from Runtime Host capability provider serving?

**ACP mode** (`--acp`) uses stdio transport and implements the ACP v1 protocol for IDE integrations and local tooling (lines 302-309). **Runtime Host capability provider serving** uses WebSocket transport (lines 254-260) to enable browser-based and remote clients. The protocols differ: ACP is request-response over pipes, while the Runtime Host variant supports persistent bidirectional connections.

### Can Runtime Host plugins be managed without restarting the service?

Yes. The `runtime-host plugin reload` command triggers hot-reloading without process restart (lines 240-251). This works because the Runtime Host maintains isolated plugin contexts that can be torn down and reconstructed. However, `install` and `uninstall` operations may require restart depending on native dependency changes—check `maka runtime-host plugin status` for pending restarts.

### Where are Runtime Host profiles stored locally?

Profile storage location depends on platform conventions as resolved in [`packages/cli/src/cli-core.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/cli-core.ts) (lines 284-306). The implementation uses the XDG Base Directory specification on Linux (`~/.config/maka/profiles/`), equivalent Library paths on macOS, and `%APPDATA%/maka/profiles/` on Windows. Run `maka runtime-host profile list --verbose` to reveal the active storage path.