helmor-cli

# Helmor CLI

Use this skill to guide simple terminal-first Helmor workflows. Keep the answer practical: prefer one or two concrete commands over a long CLI tutorial.

## Command Routing

Route by the first word after `/helmor-cli`:

- `restack` — re-sync a PR stack after a lower layer changed or merged. Follow `references/restack.md`. (This is what the composer's **Restack** button sends.)
- `stack` — plan and build a large change as a stack of dependent PRs. Follow `references/stacked-pr.md`.
- `break` — split the change you've ALREADY written in the current workspace into a stack of smaller dependent PRs, confirming the slicing granularity with the user first. Follow `references/break.md`.
- Anything else (or no argument) — an ordinary Helmor CLI task; use the binary-name guidance and command reference below.

## Binary Name (Release vs Dev)

Examples below use the literal name `helmor` — the binary a release user has on their PATH.

- **Release builds**: invoke commands as `helmor <subcommand>`.
- **Dev builds**: do NOT assume `helmor-dev` is on PATH. Under Helmor's worktree-based dev workflow every worktree has its own `target/debug/helmor-cli`, and a shared `/usr/local/bin/helmor-dev` symlink (if it exists) can only point at one of them. Instead:
  - If you're an **agent running inside Helmor**, the system prompt has already handed you the exact CLI invocation to use (typically an absolute path like `<worktree>/src-tauri/target/debug/helmor-cli`). Call it verbatim — don't re-verify with `which` / `file` / `--version`.
  - If you're a **human at a terminal**, run `<your-worktree>/src-tauri/target/debug/helmor-cli <subcommand>` (or whatever path your active Helmor build uses).

The rest of every command shape is identical regardless of build.

## First Checks

1. Check whether the CLI is installed and which data mode it targets:

```bash
helmor cli-status
```

2. Check the active data directory and database:

```bash
helmor data
```

Use `--json` when the output will be parsed by scripts or another tool.

## CLI Install And Update

Treat Helmor CLI install/update as beta.

- Prefer the Helmor desktop onboarding/settings Components panel for installing or repairing the managed CLI entrypoint.
- Use `helmor cli-status` to verify whether the PATH entry points at the current app-managed CLI.
- Do not invent a stable standalone install/update command unless it exists in `helmor --help` or a subcommand help page.
- If the user is blocked, ask them to run `helmor cli-status` and share the output, or inspect the app's Components panel if working inside the Helmor repo.

## Helmor Skills Install And Update

Treat Helmor skills install/update as a beta app-managed flow.

- Prefer the Helmor desktop onboarding/settings Components panel for installing or updating bundled Helmor skills.
- Do not invent a `helmor skills` command; the top-level CLI help does not currently expose one.
- If the user asks to update a bundled Helmor skill inside the repo, edit the skill files directly and validate them with the skill validation tooling.
- Keep user-facing skill content concise and English-first unless the user explicitly asks for another language.

## Common Tasks

### Manage Repositories And Workspaces

Use these command groups for local-first project setup and workspace orchestration:

```bash
helmor repo --help
helmor workspace --help
```

When creating workspaces, prefer explicit repo names and concise purpose labels:

```bash
helmor workspace new --repo helmor
```

### Inspect Sessions And Files

Use sessions for conversation history and files for editor-surface operations:

```bash
helmor session --help
helmor files --help
```

### Send A Prompt To An Agent

Use `send` when the user wants to dispatch work from the terminal:

```bash
helmor send --help
```

Favor JSON output for automation:

```bash
helmor --json send --help
```

### Integrations And Local Tooling

Use the relevant command group:

```bash
helmor github --help
helmor scripts --help
helmor models --help
```

### MCP Server

Run Helmor as an MCP server over stdio:

```bash
helmor mcp
```

Use this when another agent/runtime needs to call Helmor through Model Context Protocol.

## Command Reference

Read `references/helmor-help.md` when you need the full top-level `helmor --help` command list.

For exact flags on a command group, run the group's help instead of guessing:

```bash
helmor <command> --help
```