shelbi issue

shelbi issue <SUBCOMMAND> [OPTIONS]

shelbi issue is the CLI face of the Kanban board. Each card is a file under ~/.shelbi/projects/<project>/tasks/; each column transition appends a line to ~/.shelbi/events.log. The TUI's issues pane and this command are two views on the same files. The orchestrator drives the board through it, and it's where scripting, automation, and one-off fixes live.

A board mid-flight, with one issue promoted to TO DO, one dispatched to a workspace, and one already DONE:

                              
 shelbi                       
                              
                              
  🔍 Search               ⌃P  
                              
                              
  💬 Orchestrator             
                              
  📋 Issues                   
                              
  🚀 Changelog                
                              
                              
 — Workspaces —               
 ▾ hub                        
   · alpha               idle 
   · bravo               idle 
 ▾ devbox                     
   ⏵ delta          Developer 
                              
   ⚙     📣                   
                              

 Issues · shelbi   5 total                                                    Workflow: All ▾ Workspace: All ▾ 
                                                                                                               
 BACKLOG (2)              TO DO (1)                IN PROGRESS (1)           R   DONE (1)                  C   
 Audit third-party        Write CLI reference      Write changelog page      E   Getting-started           A   
 licenses                 pages                     task  ⎇ you/t-013        V   section                   N   
  task                     task                                              I    task                     C   
                                                                             E                             E   
 Draft Q3 roadmap                                                            W                             L   
  task                                                                                                     E   
                                                                            (0)                            D   
                                                                                                               
                                                                                                          (0)  
                                                                                                               
  h/l col   j/k row   ⏎ open   ⇧h/⇧l move col   ⇧k/⇧j reorder   ⇥ workflow   f filter   / search   r refresh   

Every subcommand accepts the global -p / --project <PROJECT> flag: it targets the named project, otherwise $SHELBI_PROJECT or the registered project whose work_dir contains the current directory. It's omitted from the per-subcommand tables below.

add

shelbi issue add [OPTIONS] <TITLE>

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

list

shelbi issue list [OPTIONS]

Print every issue grouped by column, in priority order within each column. Use --status <NAME> to scope to one status, or --ready to see only unblocked todo items in dispatch order. That's the orchestrator's view of "what should I assign next." --workflow <NAME> narrows either view to a single workflow.

show

shelbi issue show <ID>

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

depends

shelbi issue depends [OPTIONS] <ID>

Edit an issue's dependency list without opening the file.

move

shelbi issue move --to <STATUS> [OPTIONS] <ID>

Move an issue between statuses. Promoting to todo is the orchestrator's start signal. It picks a free workspace and runs issue start itself.

The destination is validated against the issue's workflow. A status the workflow doesn't declare errors with the list of statuses it does declare, and the issue stays put. The core statuses accept friendly spellings in any case (InProgress, wip, to-do, cancelled, completed, …); a custom status id must match exactly. An issue pinned to a workflow with no YAML on disk falls back to the built-in default (with a warning), so projects keep moving while the workflows directory is empty.

Moving across an edge that declares transition actions runs them. A merge action is gated: the branch is merged before the card moves, and a failed merge leaves the issue where it was. A move into in_progress also cuts the issue's branch on the hub first.

assign

shelbi issue assign --to <WORKSPACE> <ID>

Set the issue's assigned_to field without launching the workspace. Use this when you want to pre-allocate before promoting to todo. The workspace must be declared in the project YAML. A workspace already running a different in_progress issue is refused.

unassign

shelbi issue unassign <ID>

Clear an issue's assigned_to field. The issue stays in its current column.

start

shelbi issue start [OPTIONS] <ID>

Launch the assigned workspace on this issue. Three things happen in one shot:

1. The workspace's worktree is checked out to the issue's branch (generated from workflow config, project config, or your GitHub username when unset).
2. Any existing session for that workspace is ended. Context is wiped clean.
3. The runner relaunches with the issue prompt and the column transitions into in_progress.

Pass --workspace to assign and launch in one call. This is the command the orchestrator runs when an issue hits todo.

resume

shelbi issue resume [OPTIONS] <ID>

Relaunch the assigned workspace on the issue it is already working, without throwing away progress. Use it when a worker stalls or its session dies (a killed or wedged session, an agent that stopped mid-issue) and you want it going again on the same issue with its work intact.

resume is the recovery counterpart to start. start wipes the agent's context (ends the session and re-checks-out a clean branch): right for a fresh dispatch, wrong for recovery. resume instead preserves the in-flight state:

1. The workspace's worktree is left as-is: its branch, commits, and uncommitted changes stay exactly where the worker left them. The branch is never reset or re-checked-out. (If the worktree was torn down entirely, it's recreated on the issue's existing branch.)
2. The runner session is recreated or reclaimed: a killed session is stood back up, and a stale or wedged one (the duplicate-session case) is torn down before the fresh session comes up.
3. For a claude runner the session relaunches with --continue, so the worker reloads its prior conversation and picks up mid-thought with full context. Other runners fall back to re-injecting the issue prompt. The agent continues by reading its own prior work in the worktree. Either way the prompt is auto-submitted.

If the card has drifted out of in_progress (a killed worker whose issue someone moved back), resume restores it.

prio

shelbi issue prio [OPTIONS] <ID>

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

Pass exactly one of these flags.

edit

shelbi issue edit <ID> [OPTIONS]

With no flags, opens the issue's frontmatter and body in $EDITOR for free-form edits. On the file_system backend that's the issue's markdown file. On a remote tracker such as GitHub it's a local copy of the same document, and saving writes back what you changed: the title, the body, and the metadata block. A field someone else changed while the editor was open is kept unless you changed it too, in which case nothing is saved. The column, priority, and assigned_to fields have dedicated commands, so an edit to them on a remote tracker is refused. When a save can't land, the error says where your edits were kept.

Any field flag switches to non-interactive mode, the path for the orchestrator, CI, or a script to revise an issue after creation. A non-interactive edit bumps updated_at, validates the touched fields before writing, and emits an edited event so the change is visible to the board and the activity feed. Fields that already have a dedicated command (move, prio, assign, depends) are out of scope; use those.

The body sources (--body, --body-file, stdin) are mutually exclusive with each other and with the substitution flags. Substitutions replace all occurrences of each match and report a per-substitution count; multiple --sub/--sub-regex apply in command-line order, each operating on the previous one's output. Editing an issue whose column is an active status (e.g. in_progress) prints a warning: the running worker won't see the change until the issue is re-dispatched with shelbi issue start.

# Fix a stale path and swap a value in place, before dispatch.
shelbi issue edit fix-login-flow \
    --sub "src/old_auth.rs" "src/auth.rs" \
    --sub-regex "timeout=([0-9]+)" "timeout=30"
 
# Append a late acceptance criterion without rewriting the body.
shelbi issue edit fix-login-flow --append <<'EOF'
- [ ] Session cookies are cleared on logout.
EOF

rm

shelbi issue rm <ID>

Delete an issue. On the file_system backend this removes its markdown file; on a github board it closes the GitHub issue as not planned (GitHub can't delete issues). Either way the column's priorities are renumbered.

comment

shelbi issue comment <ID> <TEXT>

Post a comment on an issue. It works against whichever backend the project is configured for: on the default file_system board the comment is a local markdown file; on a github board it is a native GitHub issue comment. See the GitHub Issues backend.

issue-store migrate

shelbi issue-store migrate --to <BACKEND> [--dry-run] [--pace-secs <SECS>]

issue-store is a sibling top-level command that operates on the backend itself. Its one subcommand, migrate, moves the project's issues between the file_system and github backends, matched on the stable Shelbi id so a re-run never duplicates an already-migrated card. The source is the other live backend: --to github reads the on-disk board and creates issues; --to file_system reads GitHub issues and writes markdown files.

After the migration completes, switch the project's issue_tracker.backend to the new backend. See GitHub Issues backend.

Examples

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

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

Promote a triaged issue to todo, and the orchestrator picks it up:

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

Reorder ready work so a specific issue is dispatched first:

shelbi issue prio fix-sidebar-clamp --top

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

shelbi issue start docs-write-changelog-page --workspace delta

Recover a stalled worker without losing its in-flight work, relaunching the pane and resuming the conversation on the same issue:

shelbi issue resume docs-write-changelog-page

See also

• Workflows — the schema behind --workflow, what --to is validated against on issue move, and the default workflow's lifecycle (who moves an issue between which statuses).
• shelbi workflow — list, show, scaffold, and edit the workflow YAMLs issues run under.
• Workspaces — the pool model that assign / start route into.
• Orchestrator — how --reason tags get parsed by the scheduler.
• GitHub Issues backend: how these subcommands behave when the board is GitHub issues rather than local markdown.