diff options
Diffstat (limited to 'makima/docs/CLI.md')
| -rw-r--r-- | makima/docs/CLI.md | 669 |
1 files changed, 669 insertions, 0 deletions
diff --git a/makima/docs/CLI.md b/makima/docs/CLI.md new file mode 100644 index 0000000..5246a30 --- /dev/null +++ b/makima/docs/CLI.md @@ -0,0 +1,669 @@ +# 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 |