helmor-cli - SKILL.md Agent Skill

name: helmor-cli description: Use the Helmor CLI to remote-control Helmor from the terminal. Use when the user asks to inspect Helmor data/settings, manage repositories/workspaces/sessions/files, send prompts to agents, list models, use GitHub integration, inspect scripts, migrate from Conductor, run Helmor as an MCP server, generate shell completions, quit a running app, check/install/update the Helmor CLI beta, install/update Helmor skills through the beta app flow, or needs the Helmor command reference. Also plan and build a large change as a stack of dependent PRs (`/helmor-cli stack`), split a change you've already written into a stack (`/helmor-cli break`), and re-sync a stack after lower layers change or merge (`/helmor-cli restack`).

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

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

helmor cli-status

Check the active data directory and database:

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:

helmor repo --help
helmor workspace --help

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

helmor workspace new --repo helmor

Inspect Sessions And Files

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

helmor session --help
helmor files --help

Send A Prompt To An Agent

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

helmor send --help

Favor JSON output for automation:

helmor --json send --help

Integrations And Local Tooling

Use the relevant command group:

helmor github --help
helmor scripts --help
helmor models --help

MCP Server

Run Helmor as an MCP server over stdio:

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:

helmor <command> --help