Skip to main content

Keel CLI Overview

Keel is a command-line product, not a fallback shell around some hidden primary interface. The commands are how the board is inspected, changed, and trusted.

Public Contract

The CLI is the product surface

Keel is not a hidden engine behind a UI. The board, the artifacts, and the command line are one operating contract that humans and AI harnesses can share.

Vendor Neutral

The interface works across harnesses

Keel does not assume a specific editor, model vendor, or chat shell. The CLI keeps the operating model portable across different agent setups.

Layered

You do not need every command on day one

The command families are intentionally staged. Orientation and pull commands come first, then planning, then deeper automation and maintenance surfaces.

The command families​

The Fixer

Orientation and integrity

Read the pacemaker, health, and board flow before you create more motion. These surfaces tell you whether the system should be trusted first.

  • doctor
  • health
  • heartbeat
  • flow
  • screen

The Operator

Pull and close delivery slices

Use the workbench and role-scoped queues to pull one executable move, attach proof, and close the slice without guessing.

  • workshop
  • turn
  • roles
  • next
  • story
  • verify
  • audit

The Architect

Shape missions, plans, and constraints

These commands create the strategic and tactical structure that keeps delivery work bounded and reviewable.

  • mission
  • epic
  • voyage
  • routine
  • adr
  • roadmap
  • finance

Discovery

Research, topology, and automation

Use these surfaces when you need to reduce fog, inspect the board graph, or run a bounded automation cycle.

  • play
  • bearing
  • knowledge
  • pulse
  • topology

Comms

Agent-to-agent signaling

Inbox and ping surfaces let teams coordinate through a visible repository-level channel instead of private memory.

  • ping
  • poke
  • inbox
  • outbox

Setup

Install and maintain the engine

These commands scaffold a downstream project, upgrade the installed binary, refresh generated artifacts, install hooks, and inspect repo-local configuration.

  • upgrade
  • new
  • config
  • generate
  • hooks

Read the CLI in layers​

For onboarding and day-one use, start with this narrow sequence:

keel health --scene
keel heartbeat
keel flow --scene
keel next --role operator

That sequence answers four different questions:

  • Is the board structurally healthy?
  • Is the pacemaker energized?
  • Is the delivery circuit open, healthy, and moving?
  • What is the next role-scoped move?

keel flow --scene is a delivery-readiness surface, not a verbatim echo of keel doctor. During energized mission intake, the flow circuit can stay open with a warning notice even while doctor still reports transitional mission-wiring debt.

Once that loop feels natural, expand outward into planning commands such as mission, epic, voyage, and adr, then deeper maintenance surfaces such as pulse, topology, and knowledge.

Two additional inspection surfaces become useful as soon as the board starts to feel real:

keel turn
keel roles
  • keel turn exposes the canonical operating rhythm directly instead of leaving it only in docs prose.
  • keel roles exposes the configured lane and contract model directly instead of burying it inside config and implicit next behavior.

External ingress is still a CLI contract​

For normal day-one use, planning enters Keel through direct mission, epic, voyage, and story commands.

When Keel sits inside a larger runtime such as Keeper, the public boundary is still CLI-first: providers should normalize into a formal mission request envelope and lower through Keel commands instead of mutating board artifacts out-of-band.

The documented direction is a native keel mission request ... namespace for that ingress path. Until it ships, treat it as an architectural contract rather than a required onboarding command family.

Read Keeper Boundary And Mission Requests for the ownership split between Keel and Keeper, the first GitHub issue request format, and the multiplayer security boundary.

The CLI is designed to be read by both humans and agents​

The same surface should work in three modes:

  • interactive reading in a terminal
  • automation-friendly output such as --json
  • compact visual diagnosis through --scene

That is why the CLI matters so much in Keel. It is not just an admin tool. It is the operating grammar of the system.

Next stops​