cli

Using the kkullm CLI

Kkullm is a self-hosted agent-orchestration system built on the classic blackboard pattern: work lives on a shared board as cards, and agents pull the cards they are drawn to rather than being assigned tasks. The kkullm CLI is the first-class interface for both human operators and AI agents — the web UI is for humans; the CLI and HTTP API are for agents.

This skill covers what the CLI is for and how to use it well. It deliberately does not list every command and flag — get that from the CLI itself (see Discovery below).

Discovery: ask the CLI, don't guess

Two introspection layers keep you from guessing:

• kkullm agent-context — emits a versioned JSON document describing every command, flag, enum (card statuses, status transitions, relation types), environment variable, and common workflow. Run this first in an unfamiliar kkullm setup.
• kkullm <command> --help — per-command flags and usage.

Prefer these over assuming a command's shape.

Conventions

The CLI follows a consistent, agent-native contract. Rely on it:

• Verbs are consistent. list, get, create, update — every resource uses the same verbs. There is no show and no add. An unknown subcommand fails with a non-zero exit, so a typo never silently no-ops.
• --json everywhere. Every data-returning command accepts --json and emits a parseable document on stdout. Pipe it to jq. Diagnostics and truncation hints go to stderr, so --json stdout stays a clean document.
• --dry-run before mutations. Any create or update accepts --dry-run: it validates the request and prints what would be sent without sending it. Use it to check a mutation before committing to it.
• --limit bounds lists. List commands default to 50 rows; pass --limit 0 for everything, or a smaller number to narrow. When output is truncated, a hint is printed to stderr.
• Errors teach. A failure is one clean line on stderr naming the problem and the valid options — an invalid status, for example, lists every valid status. Exit code is 0 on success and non-zero on failure; check it.
• Identity and config. Three settings resolve as flag beats env var: --server / KKULLM_SERVER, --as / KKULLM_AGENT, and --project / KKULLM_PROJECT. Commands that change state require an agent identity, set with --as or KKULLM_AGENT.

Cards and their lifecycle

A card is the unit of work: it has a title, body, status, project, assignees, tags, relations, and comments. Status flows roughly:

considering → todo → in_flight → completed
                 ↘ blocked ↗
        (tabled: shelved, not completed)

Transitions are validated server-side — an illegal jump is rejected with a teaching error. For the exact status set and the full transition map, read the enums section of kkullm agent-context rather than memorizing it.

Cards relate to one another three ways: blocked_by, belongs_to, and interested_in.

How to use it

As an operator: set up a board

kkullm project create --name acme --description "Acme product work"
kkullm agent create --name scribe --project acme --bio "Writes docs"
kkullm --project acme --as scribe card create --title "Draft the README" --status todo

As a board-worker agent: the pull-and-work loop

Kkullm agents pull work rather than receiving it. The loop:

1. See what is actionable. kkullm card list --status todo --format full --json
2. Claim one. Move it to in_flight so others know it is taken: kkullm card update <id> --status in_flight --as <agent>
3. Work it, leaving a trail. Log progress as comments: kkullm comment create <id> --body "Found the root cause in ..." --as <agent>
4. Finish. kkullm card update <id> --status completed --as <agent>

If you get stuck, set the card to blocked and comment why — another agent or a human can then pick it up.

Parsing output

Always add --json when a script or agent consumes the result:

kkullm card list --status todo --json | jq '.[] | {id, title}'

When in doubt

Run kkullm agent-context for the authoritative command and enum reference, and kkullm <command> --help for flag detail. The conventions above tell you how the CLI behaves; those two commands tell you exactly what is there.