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:

helmor cli-status

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

/helmor-cli break — split an existing change into a stack

break is the mirror of stack: instead of planning a stack from scratch, it takes the change you've already written in the current workspace and carves it into a stack of small, dependent PRs — confirming the slicing granularity with the user before committing to anything. The output is the normal stack: one workspace + PR per slice, nested in the sidebar.

Input: the current workspace's full diff vs its base branch. The current workspace becomes the stack's root, so capture a recovery ref before you rewrite anything:

git commit -am "WIP: snapshot before break"   # only if the working tree is dirty
ORIG=$(git rev-parse HEAD)                      # the full change you're slicing
git branch helmor/break-backup "$ORIG"          # named recovery point

Source every slice below from $ORIG (not the branch name) — once the root is reset, the branch no longer points at the full change.

Workflow

1. Analyze the diff

git diff --name-status <base>...

(<base> is the workspace's target branch, e.g. origin/main — the system prompt tells you which.) Read the changed files and their add/modify/delete status, and group them by concern (schema/data, backend/API, UI, tests, docs…).

2. Propose a slicing

Build a dependency-ordered list of slices (bottom depends on nothing new; top depends on everything below), e.g. db → api → ui. For each slice give: a title, the files it contains, and the one-line reason it depends on the slice below. Show the full proposal.

3. Confirm granularity WITH the user — the point of break

Do NOT auto-split. Present the proposal and let the user steer the granularity with structured choices:

• Approve as-is.
• Coarser — merge two adjacent slices.
• Finer — split a slice (e.g. pull tests into their own layer).
• Move a file — reassign a file to a different slice.
• Reorder — fix the dependency order.

Loop until the user approves. Also proactively ask about ambiguous files — a single file whose changes span concerns (e.g. utils.ts with both schema and UI helpers): keep it whole in one slice, or flag it for a manual hunk-level split (out of scope for v1 — see Limits).

4. Materialize the stack (bottom-up) — your current workspace becomes the root

The workspace you're in becomes the bottom layer; only the higher layers are new workspaces. No throwaway launchpad, nothing to delete afterward.

For each slice K, from the bottom up:

1. Get the layer's workspace:

• bottom slice (root) = your current workspace — reset it onto the base and

rebuild it as slice 1 only:

     git reset --hard <base>                  # e.g. origin/main — the slicing base
     git checkout "$ORIG" -- <slice-1 added/modified files>
     git rm <slice-1 deleted files>           # if any
     git commit -m "<slice 1 title>"

• every higher slice: helmor workspace new --parent <slice K-1 workspace>

(the first higher layer's --parent is your current workspace). 2. Apply only slice K's files onto that layer (it already contains slices 1..K-1 because it forked off the layer below), sourcing from $ORIG:

• added / modified files: git checkout "$ORIG" -- <files>
• deleted files: git rm <files>
• then commit with the slice title.

Drive each higher layer with a focused dispatch so it works inside its own worktree (pass $ORIG's SHA explicitly; helmor/break-backup resolves it too):

   helmor send --workspace <id> --plan "Apply ONLY these files from <ORIG-sha>: <list>. \
   Added/modified: git checkout <ORIG-sha> -- <files>. Deleted: git rm <files>. \
   Commit as '<title>'. Do not touch anything else."

Result: layer K = base + slices 1..K (cumulative); the top layer reproduces the original change exactly.

5. Verify lossless

The stack must reproduce the original exactly:

git diff "$ORIG" <top-layer-branch>

This must be empty. Empty = the top of the stack has the same tree as the original → nothing was dropped or duplicated. If it is not empty, STOP and report the difference — and restore the root with git reset --hard helmor/break-backup.

6. Hand off

Your current workspace is now the stack's root; the higher layers are the only new workspaces (helmor workspace stack <top> shows the chain; the sidebar nests them). Open PRs bottom-up. Consider retitling the root to its slice-1 title. Once you've confirmed the split is faithful, the recovery branch is yours to keep or drop (git branch -D helmor/break-backup).

Limits (v1)

• File-level slices only: a file goes wholesale into one slice. Splitting a

single file's changes across slices (hunk-level) isn't supported yet — flag such files in step 3 and keep them in one slice.

• Slices must partition all changed files; the step-5 lossless check

enforces it.

• Root = your current workspace: its branch is rewritten in place to become

slice 1. The full change stays recoverable at helmor/break-backup (and is reproduced at the stack tip + checked in step 5), so it's safe — but unlike a fresh-stack build, the starting branch is rewritten. Higher layers are new workspaces.

Helmor CLI Top-Level Help

Captured from helmor --help.

Remote-control Helmor from the terminal. Works against the same SQLite database the desktop app uses — run commands even while the app is running.

Usage: helmor [OPTIONS] <COMMAND>

Commands:
  data         Data directory, database, and mode info
  settings     App settings stored in `settings` table
  repo         Repository registration and configuration
  workspace    Workspace CRUD, branching, syncing, archiving
  session      Session CRUD and inspection
  files        File listing, reading, writing, staging (editor surface)
  send         Send a prompt to an AI agent
  models       List available AI models
  github       GitHub integration — auth, PR lookup, merge
  scripts      Inspect repo-level setup/run/archive scripts
  conductor    Migrate from Helmor v1 (Conductor)
  completions  Shell completion scripts
  cli-status   Report whether the current Helmor CLI entrypoint is installed to PATH and which data mode it uses
  quit         Ask a running Helmor app to quit (noop when it isn't running)
  mcp          Run as an MCP (Model Context Protocol) server over stdio
  help         Print this message or the help of the given subcommand(s)

Options:
      --json
          Emit JSON instead of human-friendly text

      --quiet
          Reduce output to IDs / nothing. Useful for scripting

      --data-dir <DIR>
          Override the data directory (default: ~/helmor or ~/helmor-dev)

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

/helmor-cli restack — re-sync a PR stack after lower layers changed

Restack propagates changes up a stack: after a lower layer gets new commits (or merges), every layer above it is out of date and must pull the new base. This is the "brain" behind the composer's Restack button (it appears on a stack tip and sends /helmor-cli restack).

In Helmor each layer's target branch is its parent's branch, so restacking = syncing each layer with its parent, bottom-up. v1 is merge-based — no rebase, no force-push — matching helmor workspace sync.

Workflow

1. Map the stack

Run helmor workspace stack <current-workspace-ref> (add --json to parse) to see the full chain root → tip: each layer's branch, target, PR, and status. You're typically invoked from the tip.

2. Sync bottom-up

Walk the chain from the bottom up (skip the root — its base is main, not another layer). For each layer in order:

1. If the layer below has local commits the child still needs on its remote, push it first: helmor workspace push <lower-ref>. 2. Pull the parent's latest into this layer: helmor workspace sync <this-ref> — merges this layer's target (its parent's branch) in.

sync reports an outcome: Updated, AlreadyUpToDate, Conflict, or StashPopConflict.

3. Stop on conflict

If any sync reports a conflict, STOP. Tell the user which layer conflicted and the files involved — do not try to auto-resolve. Let them resolve in that workspace, then re-run /helmor-cli restack.

4. Report

Summarize per layer (synced / already up to date / conflicted) and name the next layer to review.

Notes

• Restack is manual for now (the button or this command). Automatic restack-on-merge is a planned Helmor feature.
• Never rebase or force-push in v1 — stay merge-based via helmor workspace sync.
• When the bottom PR merges into main, the next layer should re-target main before syncing: helmor workspace target-branch set <ref> main, then helmor workspace sync <ref>.
• Stop for the user before any risky git operation (dirty worktrees, multi-branch pushes, conflict resolution).

Stack spec — format & canonical diagram

The stacked-pr skill renders its diagram from a JSON stack spec via scripts/render_stack.py. The renderer derives all column widths from the data, so every stack comes out in the same shape. Do not hand-draw the diagram — always render through the script so output is byte-for-byte consistent.

Spec shape

Layers are ordered tip → root — the newest PR (top of the stack) first, the base-most PR last.

{
  "name": "dark-mode",
  "repo": "helmor/uranus",
  "base": "main",
  "layers": [
    {"pr": "483", "title": "feat: dark mode toggle",  "state": "draft",  "ws": "dark-mode-ui"},
    {"pr": "482", "title": "feat: persist theme pref", "state": "open",   "ws": "dark-mode-api"},
    {"pr": "481", "title": "feat: add theme column",   "state": "merged", "ws": "dark-mode-schema"}
  ]
}

The base ◂ pointer for each layer is derived: it points at the PR of the layer immediately below, and the bottom layer points at base. The ← HEAD marker is always on layers[0] (the tip).

State glyphs (legend)

Canonical output (style A)

Running the spec above produces exactly:

stack: dark-mode · helmor/uranus · 3 PRs

◉ #483  feat: dark mode toggle      draft    ← HEAD
│  └ ws: dark-mode-ui      base ◂ #482
│
◉ #482  feat: persist theme pref    open
│  └ ws: dark-mode-api     base ◂ #481
│
✓ #481  feat: add theme column      merged
│  └ ws: dark-mode-schema  base ◂ main
┴ main

Read it top-down: the tip (#483, newest) is on top and sorts into the sidebar normally; each lower PR is the base of the one above it; main is the stack's foundation at the bottom. This is the textual twin of how the Helmor sidebar groups the stack's workspaces.

/helmor-cli stack — plan & build a stacked PR

Turn a large change into a stack of small, dependent PRs — each PR builds on the one below instead of all branching from main. This keeps every PR small and reviewable while you keep moving, without waiting for the previous one to merge.

In Helmor a stack is a chain of workspaces: one workspace = one branch = one PR, linked by parentWorkspaceId. The sidebar groups a stack's workspaces together (tip on top, base at the bottom); gh pr create --base automatically targets the parent branch.

Workflow

1. Investigate prior art FIRST

Before proposing a stack, check whether related work already exists, so you extend it instead of duplicating it.

• helmor workspace list --json — scan open workspaces for related branches or an in-flight stack (rows in the same repo, or already linked by a parent).
• helmor workspace stack <ref> — if a candidate is already stacked, see its whole chain.
• helmor workspace show <ref> — inspect a candidate's branch, target, and PR.
• gh pr list / search the repo — find related open PRs and code.

Report what you found in one line, e.g. "you already have open PR #481 adding the schema column — the stack can start on top of it" — that beats starting from scratch.

2. Decompose into an ordered stack

Break the task into the smallest sequence of PRs where each depends only on the ones below it. Order bottom-up by dependency, e.g. data/schema → backend → UI. For each layer, state the one-line reason it depends on the layer below.

3. Render the plan — always, deterministically

Always render through the bundled script so the diagram is byte-for-byte identical every time — never hand-draw the ASCII. Two sources, one renderer:

• From a stack that already exists (workspaces are created): pipe the live data straight through —

  helmor workspace stack <ref> --json | python3 scripts/render_stack.py -

• From a plan you're proposing (nothing created yet): build a JSON stack spec (see references/stack-spec.md, layers ordered tip → root) and render it —

  python3 scripts/render_stack.py /path/to/spec.json

(Sanity-check the renderer any time with python3 scripts/render_stack.py --selfcheck.) Show the rendered stack to the user before creating anything.

4. Grow the stack lazily — one layer at a time

Do not create every workspace up front (you'll guess the decomposition wrong before you've learned anything). Create the bottom layer, build it, then grow upward as each layer stabilizes:

• Bottom of the stack = your current workspace (the one you're running in). It already targets the repo's default branch, so build the first layer's change directly here — do NOT spin up a separate --repo workspace for the base. The workspace you started from becomes the stack's root, instead of being left behind as an empty launchpad to delete later.
• Each higher layer (forks off the layer below; its PR targets the parent): helmor workspace new --parent <lower-workspace-ref> — the first higher layer's <lower-workspace-ref> is your current workspace.

--parent records parentWorkspaceId and materializes the child's target branch to the parent's branch — so the sidebar nests the stack and gh pr create --base targets the parent with no extra steps. The child forks off the parent's branch tip (published origin/<branch> if pushed, else the local tip), so you can stack before pushing.

5. Ship bottom-up

Ship and merge the bottom PR first. After a lower layer changes or merges, re-sync the layers above it with /helmor-cli restack (see references/restack.md).

Notes

• Keep each PR small and independently reviewable — that's the whole point of stacking.
• The diagram from step 3 is the textual twin of the sidebar's stack grouping — same order (tip on top, base at the bottom). Keep them consistent by always rendering through the script.
• A stack is single-repo: every layer lives in the same repository as its parent.