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

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. This article examines all operational modes as implemented in 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

# 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). 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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	Bootstraps launchMakaCli
Core dispatcher	packages/cli/src/cli-core.ts	Parses arguments, routes to mode handlers
Type definitions	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	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

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, 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 (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.

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