Shelbi

shelbi task

Manage the project's Kanban task board — add, list, move, assign, and start tasks from the CLI.

shelbi task

shelbi task <SUBCOMMAND> [OPTIONS]

shelbi task is the CLI face of the Kanban board. Every card on the board is a file under ~/.shelbi/projects/<project>/tasks/ and every column transition becomes a line in ~/.shelbi/events.log. The TUI's tasks pane is one view on top of this; the CLI is another. The orchestrator drives the board through this command — most user-facing edits flow through the kanban view, but scripting, automation, and one-off fixes all live here.

Every subcommand accepts the global -p / --project <PROJECT> flag to target a specific project (otherwise the active $SHELBI_PROJECT or the closest .shelbi/project marker wins). It's omitted from the per-subcommand tables below to keep them readable.

add

shelbi task add [OPTIONS] <TITLE>

Create a new task. Lands in backlog by default — your inbox for triage. Pass --column todo to skip triage when you're already sure.

FlagTypeDefaultDescription
<TITLE>string—Human-readable title (positional, required).
--id <ID>stringslug of titleOverride the auto-generated id.
--column <COLUMN>stringbacklogInitial column.
-d, --description <DESCRIPTION>stringemptyTask body. Use shelbi task edit later if omitted.
--depends-on <ID>string (repeatable)—Block this task on another. Repeat for multiple deps.
--prefers-machine <NAME>string—Hint for the orchestrator to route this task to a worker on a specific machine.

list

shelbi task list [OPTIONS]

Print every task grouped by column, in priority order within each column. Use --column <NAME> to scope to one column, or --ready to see only unblocked todo items in dispatch order — that's the orchestrator's view of "what should I assign next."

FlagTypeDefaultDescription
--column <COLUMN>string—Restrict to a single column.
--readyflagoffShow only unblocked todo items, in priority order. Mutually exclusive with --column.

show

shelbi task show <ID>

Print a task's frontmatter and body, plus the resolved status of each depends_on entry. The same view the orchestrator reads before deciding whether a task is ready to dispatch.

depends

shelbi task depends [OPTIONS] <ID>

Edit a task's dependency list without opening the file.

FlagTypeDefaultDescription
--add <DEP>string (repeatable)—Dependency id to add.
--remove <DEP>string (repeatable)—Dependency id to remove.

move

shelbi task move --to <COLUMN> [OPTIONS] <ID>

Move a task between columns. Promoting a task to todo is the start signal for the orchestrator — it will pick a free worker and call task start on its own.

FlagTypeDefaultDescription
--to <COLUMN>string—Destination column (required).
--reason <REASON>stringuser:cliReason tag recorded in ~/.shelbi/events.log. The orchestrator parses this to tell auto-dispatches apart from user actions.

assign

shelbi task assign --to <WORKER> <ID>

Set the task's assigned_to field without launching the worker. Use this when you want to pre-allocate before promoting to todo. Worker must be declared in the project YAML.

FlagTypeDefaultDescription
--to <WORKER>string—Worker name (required).

unassign

shelbi task unassign <ID>

Clear a task's assigned_to field. The task stays in its current column.

start

shelbi task start [OPTIONS] <ID>

Launch the assigned worker on this task. Three things happen in one shot:

  1. The worker's worktree is checked out to the task's branch (defaults to shelbi/<task-id>).
  2. Any existing pane for that worker is killed — context is wiped clean.
  3. The runner relaunches with the task prompt and the column transitions into in_progress.

Pass --worker to assign and launch in one call. This is the command the orchestrator runs when a task hits todo.

FlagTypeDefaultDescription
--worker <WORKER>stringtask's assigned_toAssign and launch in one call.
--branch <BRANCH>stringshelbi/<task-id>Override the default branch name.
--reason <REASON>stringuser:cli:startReason tag recorded in ~/.shelbi/events.log when the column transitions to in_progress.

prio

shelbi task prio [OPTIONS] <ID>

Re-order a task within its column. The orchestrator picks the top-most ready task when dispatching, so prio is how you steer "what's next" without opening the TUI.

FlagTypeDefaultDescription
--upflag—Move up one slot.
--downflag—Move down one slot.
--topflag—Move to the top of the column.
--bottomflag—Move to the bottom of the column.
--set <N>integer—Move to a specific 0-based slot.

edit

shelbi task edit <ID>

Open the task's markdown file in $EDITOR for free-form edits.

rm

shelbi task rm <ID>

Delete a task file. Irreversible.

Examples

Triage a new request into the backlog with a dependency on existing work:

shelbi task add "Wire up changelog page" \
    --depends-on docs-write-getting-started-section

Promote a triaged task to todo — the orchestrator picks it up:

shelbi task move docs-write-cli-reference-pages --to todo

Reorder ready work so a specific task is dispatched first:

shelbi task prio fix-sidebar-clamp --top

Manually dispatch an explicit worker (overrides the orchestrator's routing):

shelbi task start docs-write-changelog-page --worker delta

See also

  • Columns — what each column means and how transitions trigger orchestrator behavior.
  • Workers — the pool model that assign / start route into.
  • Orchestrator — how --reason tags get parsed by the scheduler.