path: root/makima/docs/CLI.md

# Makima CLI Reference

Makima is a unified CLI for server, daemon, and task management. It provides commands for running the Makima server, connecting daemon workers, and orchestrating contracts and tasks.

## Table of Contents

- [Installation](#installation)
- [Commands Overview](#commands-overview)
- [Command Reference](#command-reference)
  - [makima server](#makima-server)
  - [makima daemon](#makima-daemon)
  - [makima supervisor](#makima-supervisor)
  - [makima contract](#makima-contract)
- [Configuration](#configuration)
  - [Configuration File](#configuration-file)
  - [Environment Variables](#environment-variables)
- [Usage Examples](#usage-examples)
  - [Starting the Server](#starting-the-server)
  - [Running a Daemon Worker](#running-a-daemon-worker)
  - [Contract Orchestration Workflow](#contract-orchestration-workflow)
  - [Task-Contract Interaction](#task-contract-interaction)

---

## Installation

Build and install the Makima CLI from source:

```bash
cd makima
cargo build --release
cargo install --path .
```

Or install directly:

```bash
cargo install --path makima
```

The `makima` binary will be available in your PATH after installation.

---

## Commands Overview

| Command | Description |
|---------|-------------|
| `makima server` | Run the HTTP/WebSocket server |
| `makima daemon` | Connect to server and manage tasks |
| `makima supervisor` | Contract orchestration commands |
| `makima contract` | Task-contract interaction commands |

---

## Command Reference

### makima server

Run the Makima HTTP/WebSocket server that coordinates daemons and manages contracts.

```bash
makima server [OPTIONS]
```

#### Options

| Option | Environment Variable | Default | Description |
|--------|---------------------|---------|-------------|
| `--port <PORT>` | `PORT` | `8080` | Server port |
| `--parakeet-model-dir <PATH>` | `PARAKEET_MODEL_DIR` | `models/parakeet-tdt-0.6b-v3` | Path to Parakeet model directory |
| `--parakeet-eou-dir <PATH>` | `PARAKEET_EOU_DIR` | `models/realtime_eou_120m-v1-onnx` | Path to Parakeet EOU model directory |
| `--sortformer-model-path <PATH>` | `SORTFORMER_MODEL_PATH` | `models/diarization/diar_streaming_sortformer_4spk-v2.1.onnx` | Path to Sortformer model |
| `--database-url <URL>` | `POSTGRES_CONNECTION_URI` | - | PostgreSQL connection URI |
| `-l, --log-level <LEVEL>` | - | `info` | Log level (trace, debug, info, warn, error) |

#### Examples

```bash
# Start server on default port
makima server

# Start server on custom port with database
makima server --port 3000 --database-url "postgresql://user:pass@localhost/makima"

# Start server with custom model paths
makima server --parakeet-model-dir /path/to/models/parakeet
```

---

### makima daemon

Run the daemon worker that connects to the Makima server and executes tasks.

```bash
makima daemon [OPTIONS]
```

#### Options

| Option | Environment Variable | Default | Description |
|--------|---------------------|---------|-------------|
| `-c, --config <PATH>` | - | - | Path to custom config file |
| `--repos-dir <PATH>` | `MAKIMA_DAEMON_REPOS_DIR` | `~/.makima/repos` | Directory where repositories are cloned |
| `--worktrees-dir <PATH>` | `MAKIMA_DAEMON_WORKTREES_DIR` | `~/.makima/worktrees` | Directory where worktrees are created |
| `--server-url <URL>` | `MAKIMA_DAEMON_SERVER_URL` | `wss://api.makima.jp` | WebSocket server URL |
| `--api-key <KEY>` | `MAKIMA_DAEMON_SERVER_APIKEY` | - | API key for server authentication |
| `--max-tasks <N>` | - | `4` | Maximum number of concurrent tasks |
| `-l, --log-level <LEVEL>` | - | `info` | Log level (trace, debug, info, warn, error) |

#### Examples

```bash
# Start daemon with CLI arguments
makima daemon --server-url ws://localhost:8080 --api-key your-api-key

# Start daemon with custom config file
makima daemon --config /path/to/config.toml

# Start daemon with environment variables
export MAKIMA_DAEMON_SERVER_URL=ws://localhost:8080
export MAKIMA_API_KEY=your-api-key
makima daemon
```

---

### makima supervisor

Supervisor commands for contract orchestration. These commands are used by orchestrators to manage tasks, branches, and pull requests.

```bash
makima supervisor <SUBCOMMAND> [OPTIONS]
```

#### Common Options

All supervisor subcommands accept these common options:

| Option | Environment Variable | Default | Description |
|--------|---------------------|---------|-------------|
| `--api-url <URL>` | `MAKIMA_API_URL` | `http://localhost:8080` | API URL |
| `--api-key <KEY>` | `MAKIMA_API_KEY` | - | API key for authentication |
| `--contract-id <UUID>` | `MAKIMA_CONTRACT_ID` | - | Contract ID |
| `--task-id <UUID>` | `MAKIMA_TASK_ID` | - | Current task ID (optional) |

#### Subcommands

##### tasks

List all tasks in the contract.

```bash
makima supervisor tasks [OPTIONS]
```

##### tree

Get the task tree structure showing parent-child relationships.

```bash
makima supervisor tree [OPTIONS]
```

##### spawn

Create and start a new task.

```bash
makima supervisor spawn <NAME> <PLAN> [OPTIONS]
```

| Argument/Option | Description |
|-----------------|-------------|
| `<NAME>` | Name of the task |
| `<PLAN>` | Plan/description for the task |
| `--parent <UUID>` | Parent task ID to branch from |
| `--checkpoint <SHA>` | Checkpoint SHA to start from |
| `--repo <URL>` | Repository URL (local path or remote) |

##### wait

Wait for a task to complete.

```bash
makima supervisor wait <TASK_ID> [TIMEOUT]
```

| Argument | Default | Description |
|----------|---------|-------------|
| `<TASK_ID>` | - | Task ID to wait for |
| `<TIMEOUT>` | `300` | Timeout in seconds |

##### read-file

Read a file from a task's worktree.

```bash
makima supervisor read-file <TASK_ID> <FILE_PATH>
```

##### branch

Create a git branch.

```bash
makima supervisor branch <NAME> [OPTIONS]
```

| Argument/Option | Description |
|-----------------|-------------|
| `<NAME>` | Branch name to create |
| `--from <REF>` | Reference (task ID or SHA) to branch from |

##### merge

Merge a task's changes to a branch.

```bash
makima supervisor merge <TASK_ID> [OPTIONS]
```

| Option | Description |
|--------|-------------|
| `--to <BRANCH>` | Target branch to merge into |
| `--squash` | Squash commits on merge |

##### pr

Create a pull request from a task's changes.

```bash
makima supervisor pr <TASK_ID> [OPTIONS]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--title <TITLE>` | - | PR title (required) |
| `--body <BODY>` | - | PR body/description |
| `--base <BRANCH>` | `main` | Base branch |

##### diff

View a task's diff.

```bash
makima supervisor diff <TASK_ID>
```

##### checkpoint

Create a checkpoint (save point) for the current task.

```bash
makima supervisor checkpoint <MESSAGE>
```

##### checkpoints

List all checkpoints for the current task.

```bash
makima supervisor checkpoints
```

##### status

Get contract status including current phase.

```bash
makima supervisor status
```

##### advance-phase

Advance the contract to the next phase.

```bash
makima supervisor advance-phase <PHASE>
```

| Argument | Description |
|----------|-------------|
| `<PHASE>` | Phase to advance to (specify, plan, execute, review) |

##### ask

Ask a question and wait for user feedback.

```bash
makima supervisor ask <QUESTION> [OPTIONS]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--choices <CHOICES>` | - | Comma-separated list of choices |
| `--context <CONTEXT>` | - | Context about what this relates to |
| `--timeout <SECONDS>` | `3600` | Timeout in seconds (default: 1 hour) |

---

### makima contract

Contract commands for task-contract interaction. These commands are used by tasks to interact with their parent contract.

```bash
makima contract <SUBCOMMAND> [OPTIONS]
```

#### Common Options

All contract subcommands accept these common options:

| Option | Environment Variable | Default | Description |
|--------|---------------------|---------|-------------|
| `--api-url <URL>` | `MAKIMA_API_URL` | `http://localhost:8080` | API URL |
| `--api-key <KEY>` | `MAKIMA_API_KEY` | - | API key for authentication |
| `--contract-id <UUID>` | `MAKIMA_CONTRACT_ID` | - | Contract ID |
| `--task-id <UUID>` | `MAKIMA_TASK_ID` | - | Current task ID (optional) |

#### Subcommands

##### status

Get the contract status.

```bash
makima contract status
```

Returns JSON with contract name, description, current phase, and status.

##### checklist

Get the phase checklist with deliverables.

```bash
makima contract checklist
```

Returns JSON with completion percentage, file deliverables, and suggestions.

##### goals

Get the contract goals.

```bash
makima contract goals
```

##### files

List all contract files.

```bash
makima contract files
```

##### file

Get a specific file's content.

```bash
makima contract file <FILE_ID>
```

##### report

Report progress on the contract.

```bash
makima contract report <MESSAGE>
```

##### suggest-action

Get a suggested next action based on contract state.

```bash
makima contract suggest-action
```

##### completion-action

Get a completion recommendation with metrics.

```bash
makima contract completion-action [OPTIONS]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--files <FILES>` | - | Comma-separated list of modified files |
| `--lines-added <N>` | `0` | Number of lines added |
| `--lines-removed <N>` | `0` | Number of lines removed |
| `--code` | - | Flag indicating code changes |

##### update-file

Update an existing contract file (reads content from stdin).

```bash
cat content.md | makima contract update-file <FILE_ID>
```

##### create-file

Create a new contract file (reads content from stdin).

```bash
cat content.md | makima contract create-file <NAME>
```

---

## Configuration

### Configuration File

The daemon loads configuration from multiple sources in order of precedence (highest first):

1. CLI arguments
2. Environment variables
3. Custom config file (if `--config` specified)
4. `./makima-daemon.toml` (current directory)
5. `~/.config/makima-daemon/config.toml` (user config)
6. `/etc/makima-daemon/config.toml` (system config, Linux only)
7. Default values

#### Example Configuration File

Create `makima-daemon.toml`:

```toml
# Server connection settings
[server]
url = "ws://localhost:8080"
api_key = "your-api-key"
heartbeat_interval_secs = 30
reconnect_interval_secs = 5
max_reconnect_attempts = 0  # 0 = infinite

# Worktree settings for task isolation
[worktree]
base_dir = "~/.makima/worktrees"
repos_dir = "~/.makima/repos"
branch_prefix = "makima/task-"
cleanup_on_start = false

# Process settings for Claude Code execution
[process]
claude_command = "claude"
claude_args = []
claude_pre_args = []
enable_permissions = false
disable_verbose = false
max_concurrent_tasks = 4
default_timeout_secs = 0  # 0 = no timeout

# Additional environment variables for Claude Code
[process.env_vars]
ANTHROPIC_API_KEY = "your-anthropic-key"

# Local database settings
[local_db]
path = "~/.makima/daemon.db"

# Logging settings
[logging]
level = "info"  # trace, debug, info, warn, error
format = "pretty"  # pretty or json

# Repository auto-clone settings
[repos]
home_dir = "~/.makima/home"

# Auto-clone repositories on daemon startup
[[repos.auto_clone]]
url = "https://github.com/user/repo.git"
branch = "main"
shallow = true

# Shorthand format also supported
[[repos.auto_clone]]
url = "github:user/another-repo"
name = "custom-name"
```

### Environment Variables

#### Daemon Environment Variables

| Variable | Description |
|----------|-------------|
| `MAKIMA_API_KEY` | API key for authentication (preferred) |
| `MAKIMA_DAEMON_SERVER_URL` | WebSocket server URL |
| `MAKIMA_DAEMON_SERVER_APIKEY` | API key (alternative) |
| `MAKIMA_DAEMON_REPOS_DIR` | Repository directory |
| `MAKIMA_DAEMON_WORKTREES_DIR` | Worktrees directory |
| `MAKIMA_DAEMON_PROCESS_MAXCONCURRENTTASKS` | Max concurrent tasks |

#### Server Environment Variables

| Variable | Description |
|----------|-------------|
| `PORT` | Server port |
| `POSTGRES_CONNECTION_URI` | PostgreSQL connection URI |
| `PARAKEET_MODEL_DIR` | Parakeet model directory |
| `PARAKEET_EOU_DIR` | Parakeet EOU model directory |
| `SORTFORMER_MODEL_PATH` | Sortformer model path |

#### Supervisor/Contract Environment Variables

| Variable | Description |
|----------|-------------|
| `MAKIMA_API_URL` | API URL for commands |
| `MAKIMA_API_KEY` | API key for authentication |
| `MAKIMA_CONTRACT_ID` | Current contract ID |
| `MAKIMA_TASK_ID` | Current task ID |

---

## Usage Examples

### Starting the Server

```bash
# Start with defaults
makima server

# Start with database
makima server --database-url "postgresql://localhost/makima" --port 8080

# Production setup
makima server \
  --port 8080 \
  --database-url "$DATABASE_URL" \
  --log-level info
```

### Running a Daemon Worker

```bash
# Quick start with CLI args
makima daemon \
  --server-url ws://localhost:8080 \
  --api-key your-api-key \
  --max-tasks 4

# Using environment variables
export MAKIMA_DAEMON_SERVER_URL=ws://localhost:8080
export MAKIMA_API_KEY=your-api-key
makima daemon

# Using a config file
makima daemon --config /etc/makima/daemon.toml
```

### Contract Orchestration Workflow

```bash
# Set up environment
export MAKIMA_API_URL=http://localhost:8080
export MAKIMA_API_KEY=your-api-key
export MAKIMA_CONTRACT_ID=your-contract-uuid

# Check contract status
makima supervisor status

# List existing tasks
makima supervisor tasks

# View task tree
makima supervisor tree

# Spawn a new task
makima supervisor spawn "Implement feature X" "Add the new feature with tests"

# Wait for task completion
makima supervisor wait <task-id> 600

# View task diff
makima supervisor diff <task-id>

# Create a PR
makima supervisor pr <task-id> \
  --title "Add feature X" \
  --body "Implements feature X with full test coverage" \
  --base main

# Or merge directly
makima supervisor merge <task-id> --to main --squash

# Ask user a question
makima supervisor ask "Which approach should we use?" \
  --choices "Option A,Option B,Option C" \
  --timeout 3600
```

### Task-Contract Interaction

When running inside a task, use contract commands to interact with the parent contract:

```bash
# Get contract context
makima contract status

# Check phase requirements
makima contract checklist

# List contract files
makima contract files

# Read a specific file
makima contract file <file-id>

# Report progress
makima contract report "Completed initial implementation"

# Get suggested next action
makima contract suggest-action

# Create a new documentation file
echo "# Architecture\n\nSystem design..." | makima contract create-file "Architecture"

# Update an existing file
cat updated_doc.md | makima contract update-file <file-id>

# Report completion with metrics
makima contract completion-action \
  --files "src/main.rs,src/lib.rs" \
  --lines-added 150 \
  --lines-removed 30 \
  --code
```

---

## Output Format

All commands output JSON to stdout for easy parsing and integration:

```bash
# Parse with jq
makima supervisor tasks | jq '.tasks[].name'

# Get specific fields
makima contract status | jq '{name: .name, phase: .phase}'

# Check completion
makima contract checklist | jq '.completion_percentage'
```

---

## Exit Codes

| Code | Description |
|------|-------------|
| `0` | Success |
| `1` | General error (authentication failed, invalid arguments, etc.) |

---

## See Also

- [Makima README](../README.md) - Project overview
- [Task Branching Plan](./PLAN-task-branching.md) - Task isolation architecture