@basementuniverse/kanbn 1.1.1 → 2.1.0

package/docs/commands/find.txt

@@ -4,10 +4,20 @@
 Search all tasks in the index and show search results. If no filters are specified, this command will list all tracked tasks.
 
 String search terms are treated as case-insensitive regular expressions.
+Date filters match a single day, or a range if the option is repeated.
+Numeric filters match a single value, or a range if the option is repeated.
 
 Only tasks that match all of the filters will be returned.
 
+Filters ignore hidden columns - use --column to exclude them.
+
+See docs/filtering-and-sorting.md for a full description of the filter model.
+
 Options:
+  {b}kanbn find --interactive{b}
+  {b}kanbn find -i{b}
+    Build search filters interactively.
+
   {b}kanbn find --quiet{b}
   {b}kanbn find -q{b}
     Only show task ids in the output.
@@ -16,6 +26,9 @@ Options:
   {b}kanbn find -j{b}
     Output results in JSON format. If used with the --quiet option, this will return an array of task ids.
 
+  {b}kanbn find --id "search term"{b}
+    Find tasks that have an id containing "search term".
+
   {b}kanbn find --name "search term"{b}
   {b}kanbn find -n "search term"{b}
     Find tasks that have a name containing "search term".
@@ -54,8 +67,26 @@ Options:
     This option can be repeated - if multiple dates are specified, find tasks that are due between the earliest and latest dates.
     The date can be in (almost) any format.
 
+  {b}kanbn find --plannedStart "date"{b}
+    Find tasks that have a planned start date that matches the specified date. The time part of the date will be ignored, unless searching between multiple dates.
+    This option can be repeated - if multiple dates are specified, find tasks with a planned start date between the earliest and latest dates.
+    The date can be in (almost) any format.
+
+  {b}kanbn find --plannedFinish "date"{b}
+    Find tasks that have a planned finish date that matches the specified date. The time part of the date will be ignored, unless searching between multiple dates.
+    This option can be repeated - if multiple dates are specified, find tasks with a planned finish date between the earliest and latest dates.
+    The date can be in (almost) any format.
+
   {b}kanbn find --assigned "name"{b}
-    Find tasks assigned to a specific user.
+    Find tasks assigned to a specific user. Use "^$" to find unassigned tasks.
+
+  {b}kanbn find --workload N{b}
+    Find tasks with a specific calculated workload.
+    If multiple values are specified, find tasks with a workload between the lowest and highest inputs.
+
+  {b}kanbn find --progress N{b}
+    Find tasks with a specific progress value (between 0 and 1).
+    If multiple values are specified, find tasks with progress between the lowest and highest inputs.
 
   {b}kanbn find --sub-task "search term"{b}
   {b}kanbn find -s "search term"{b}
@@ -90,6 +121,30 @@ Options:
 
   {b}kanbn find --<custom field name> "search term"|N|date{b}
     Find tasks with a custom metadata field that matches the search filter.
+    The custom field must be declared in the customFields project option.
     If the custom field is a string and multiple filters are specified, find tasks with a value that matches one of the inputs.
     If the custom field is numeric and multiple filters are specified, find tasks with a value between the lowest and highest inputs.
     If the custom field is a date and multiple filters are specified, find tasks with a value between the earliest and latest dates.
+    If the custom field is a boolean, use {b}--<custom field name>{b} to match true and {b}--no-<custom field name>{b} to match false.
+
+Examples:
+  {b}kanbn find --column Todo --column "In Progress" --assigned "^Ana$"{b}
+    Find tasks assigned to exactly "Ana" that are in either the "Todo" or "In Progress" column.
+
+  {b}kanbn find --tag "(^|\n)Bug($|\n)" --due "1 July 2026" --due "31 July 2026"{b}
+    Find tasks with the exact tag "Bug" that are due in July 2026.
+    Tags are matched against a newline-separated list, so anchoring on line breaks matches a whole tag.
+
+  {b}kanbn find --count-sub-tasks 1 --count-sub-tasks 99 --progress 0 -q{b}
+    List the ids of tasks that have sub-tasks but no progress yet.
+
+  {b}kanbn find --board "board-slug"{b}
+  {b}kanbn find -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+  {b}kanbn find --all-boards{b}
+    Search every board in the workspace. A task on several boards appears once, annotated with the
+    board and column it occupies on each. Without this, the search is scoped to the target board.
+    This can't be combined with {b}--sprint{b}: sprint numbers and names are relative to one board's
+    list, so there is no sensible answer across several.

package/docs/commands/gantt.txt

@@ -30,3 +30,8 @@ Options:
   {b}kanbn gantt --now "date"{b}
   {b}kanbn gantt -n "date"{b}
     Mock the current date used for the "now" line and single-date range filtering.
+
+  {b}kanbn gantt --board "board-slug"{b}
+  {b}kanbn gantt -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/help.txt

@@ -7,6 +7,7 @@ Where {b}<command>{b} is one of:
   {b}version{b} {d}.......{d} Show package version
   {b}init{b} {d}..........{d} Initialise kanbn board
   {b}board{b} {d}.........{d} Show the kanbn board
+  {b}boards{b} {d}........{d} List the boards in this workspace
   {b}task{b} {d}..........{d} Show a kanbn task
   {b}add{b} {d}...........{d} Add a kanbn task
   {b}edit{b} {d}..........{d} Edit a kanbn task
@@ -24,6 +25,7 @@ Where {b}<command>{b} is one of:
   {b}archive{b} {d}.......{d} Archive a task
   {b}restore{b} {d}.......{d} Restore a task from the archive
   {b}remove-all{b} {d}....{d} Remove the kanbn board and all tasks
+  {b}history{b} {d}.......{d} Show task history
 
 For more help with commands, try:
 

package/docs/commands/history.txt

@@ -27,3 +27,8 @@ Options:
   {b}kanbn history -t "task-id"{b}
     Filter for one or more task ids.
     This option can be repeated.
+
+  {b}kanbn history --board "board-slug"{b}
+  {b}kanbn history -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/init.txt

@@ -19,3 +19,16 @@ Options:
   {b}kanbn init --column "column"{b}
   {b}kanbn init -c "column"{b}
     Initialise a kanbn board and add the specified column. This option can be repeated to add multiple columns.
+
+  {b}kanbn init --board "board-slug"{b}
+  {b}kanbn init -b "board-slug"{b}
+    Create a secondary board beside the main one, at {b}.kanbn/board-slug.md{b}. Secondary boards
+    share the main board's task folder, so a task can appear on several boards, in a different
+    column on each. Combine with {b}-n{b}, {b}-d{b} and {b}-c{b} to set the board's name,
+    description and columns:
+      {b}kanbn init -b design -n "Design Pipeline" -c Ideas -c Designing -c "Signed Off"{b}
+    Running it again on an existing board updates its name, description and columns, exactly as
+    {b}kanbn init{b} does for the main board. A new board only picks up the default started and
+    completed columns if it actually has columns by those names, so a board with its own workflow
+    doesn't silently inherit "In Progress" and "Done".
+    The workspace has to exist first - run {b}kanbn init{b} with no {b}-b{b} to create it.

package/docs/commands/move.txt

@@ -5,7 +5,7 @@ Move an existing task to a different column or position. The task 'updated' date
 
 Options:
   {b}kanbn move "task-id" --interactive{b}
-  {b}kanbn move "task-id" -n{b}
+  {b}kanbn move "task-id" -i{b}
     Move a task interactively.
 
   {b}kanbn move "task-id" --column "column"{b}
@@ -21,3 +21,12 @@ Options:
     Move the task to a position relative to its current position in the target column.
     When specifying a negative value for N, the negative sign can be escaped with '/' or '\\' to prevent the value being recognised as an option. For example:
     {b}kanbn mv "task-1" -p \\-1 --relative{b}
+
+  {b}kanbn move "task-id" --board "board-slug"{b}
+  {b}kanbn move "task-id" -b "board-slug"{b}
+    Move the task on a board other than the main one. If the task isn't on that board yet it is
+    added, with a notice - so pulling work onto a board is one command rather than two.
+
+  {b}kanbn move "task-id" -b "board-slug" --no-add{b}
+    Refuse to move a task that isn't on the target board, instead of adding it.
+    The main board never adds implicitly: moving an untracked task there is an error either way.

package/docs/commands/remove.txt

@@ -1,12 +1,23 @@
 {b}kanbn remove "task-id"{b}
 {b}kanbn rm "task-id"{b}
 
-Remove an existing task.
+Remove an existing task. This deletes the task file and its index entry.
 
 Options:
   {b}kanbn remove "task-id" --index{b}
+  {b}kanbn remove "task-id" -x{b}
     Only remove the task from the index. The task file will not be deleted.
 
   {b}kanbn remove "task-id" --force{b}
   {b}kanbn remove "task-id" -f{b}
     Force remove the task without asking for confirmation.
+
+  {b}kanbn remove "task-id" --board "board-slug"{b}
+  {b}kanbn remove "task-id" -b "board-slug"{b}
+    Remove the task from that board. Combine this with {b}--index{b} to remove it from that board
+    only - boards own membership, so the task file and its entries on every other board are
+    untouched.
+
+  {b}kanbn remove "task-id" --all-boards{b}
+    Task files are shared between boards, so deleting one while another board still references it is
+    refused. This removes the task from every board that references it, then deletes the file.

package/docs/commands/rename.txt

@@ -11,3 +11,8 @@ Options:
   {b}kanbn rename "task-id" --name "name"{b}
   {b}kanbn rename "task-id" -n "name"{b}
     Rename the task with the specified name. This option is required if not renaming a task interactively.
+
+  {b}kanbn rename "task-id" --board "board-slug"{b}
+  {b}kanbn rename "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/restore.txt

@@ -10,3 +10,9 @@ Options:
   {b}kanbn restore "task-id" --column "column"{b}
   {b}kanbn restore "task-id" -c "column"{b}
     Restore a task from the archive and place it in the specified column.
+
+  {b}kanbn restore "task-id" --board "board-slug"{b}
+  {b}kanbn restore "task-id" -b "board-slug"{b}
+    Restore the task to that board only. Without this, the task goes back to every board it was on
+    when it was archived, in the column it occupied on each. A board that has since been deleted is
+    reported and skipped rather than failing the restore.

package/docs/commands/sort.txt

@@ -9,14 +9,16 @@ If the filter regular expression has numbered capturing groups, the value of the
 If the filter regular expression has named capturing groups, the value of all named groups will be concatenated.
 If there are multiple matches, their values will be concatenated.
 
+See docs/filtering-and-sorting.md for a full description of the sorting model.
+
 Options:
   {b}kanbn sort --interactive{b}
   {b}kanbn sort -i{b}
     Sort a column interactively.
 
   {b}kanbn sort --save{b}
-    Save the column sort settings in the index file. This means that any tasks added to the column will be automatically sorted.
-    If this option is not set, any saved sorting settings for the specified column will be removed.
+    Save the column sort settings in the index file (as a columnSorting option). This means that any tasks added to the column will be automatically sorted.
+    If this option is not set, the column is sorted once and any saved sorting settings for the specified column will be removed.
 
   {b}kanbn sort --ascending{b}
   {b}kanbn sort -a{b}
@@ -53,9 +55,18 @@ Options:
   {b}kanbn sort -e{b}
     Sort tasks by due date.
 
+  {b}kanbn sort --plannedStart{b}
+    Sort tasks by planned start date.
+
+  {b}kanbn sort --plannedFinish{b}
+    Sort tasks by planned finish date.
+
   {b}kanbn sort --assigned{b}
     Sort tasks by assigned user name.
 
+  {b}kanbn sort --progress{b}
+    Sort tasks by progress.
+
   {b}kanbn sort --sub-task "filter"{b}
   {b}kanbn sort -s "filter"{b}
     Sort tasks by sub-tasks.
@@ -96,3 +107,8 @@ Examples:
 
   {b}kanbn sort "Todo" -z -n --count-tags{b}
     Sort tasks in the "Todo" column first by name, then by the number of tags, all in descending order
+
+  {b}kanbn sort "column" --board "board-slug"{b}
+  {b}kanbn sort "column" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/sprint.txt

@@ -15,3 +15,12 @@ Options:
   {b}kanbn sprint --description "description"{b}
   {b}kanbn sprint -d "description"{b}
     Start a new sprint with the specified description.
+
+  {b}kanbn sprint --board "board-slug"{b}
+  {b}kanbn sprint -b "board-slug"{b}
+    Add a sprint from the context of another board. Sprints are workspace-level by default, so this
+    appends to the workspace list and says so. A board that declares its own {b}sprints{b} in its
+    front matter gets the sprint appended there instead, auto-named {b}{Board name} Sprint {n}{b} so
+    that two boards' sprints can't be confused.
+    A board with its own list can't see the workspace sprints at all - that's the cost of forking,
+    and it's why forking is a deliberate front-matter edit rather than a flag.

package/docs/commands/status.txt

@@ -15,7 +15,11 @@ Options:
 
   {b}kanbn status --untracked{b}
   {b}kanbn status -u{b}
-    Show a list of untracked task filenames.
+    Show a list of untracked task filenames. "Untracked" is workspace-scoped: a task is tracked if
+    any board references it, so this lists task files that are on no board at all.
+    When other boards track tasks that the target board doesn't, they're listed separately under
+    {b}tasksOnOtherBoards{b}, with the column each one occupies - the "what could I pull onto this
+    board" list.
 
   {b}kanbn status --due{b}
   {b}kanbn status -e{b}
@@ -33,3 +37,8 @@ Options:
     This option can be repeated - if multiple dates are specified, show task workloads for tasks between the earliest and latest dates.
     The date can be in (almost) any format.
     This option will be ignored if the --quiet or --sprint options are set.
+
+  {b}kanbn status --board "board-slug"{b}
+  {b}kanbn status -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/task.txt

@@ -7,3 +7,8 @@ Options:
   {b}kanbn task "task-id" --json{b}
   {b}kanbn task "task-id" -j{b}
     Show task information in JSON format.
+
+  {b}kanbn task "task-id" --board "board-slug"{b}
+  {b}kanbn task "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/validate.txt

@@ -2,10 +2,37 @@
 
 Validate kanbn index file and all task files, and report any formatting errors.
 
+If the files are valid, this also reports tasks whose started/completed dates don't match the column
+they're in - which usually means the task was moved by hand or by a merge, rather than through kanbn.
+
 Options:
   {b}kanbn validate --save{b}
     Re-save the index and task files. This will ensure that all index column sorting settings are applied and that all tasks are formatted correctly.
 
+  {b}kanbn validate --fix{b}
+  {b}kanbn validate -f{b}
+    Fill in missing started and completed dates for tasks that are sitting in a started or completed
+    column without one. Each date is taken from the task's history where the move was recorded,
+    falling back to the task's updated date and then its created date.
+    Tasks that have a completed date while sitting outside a completed column are reported but never
+    changed, because the date records something that actually happened. Use
+    {b}kanbn edit "task-id" --unset completed{b} to clear one deliberately.
+
   {b}kanbn validate --json{b}
   {b}kanbn validate -j{b}
     Output validation errors in JSON format.
+
+  {b}kanbn validate --board "board-slug"{b}
+  {b}kanbn validate -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+  {b}kanbn validate --all-boards{b}
+    Validate every board in the workspace and the tasks each of them references, rather than just
+    the target board.
+
+In a workspace with more than one board, {b}validate{b} also reports multi-board warnings - a
+workspace-scoped option in a board file, several boards stamping the same shared date, sprints out
+of order, a task on no board at all, history naming a board that has been deleted, and markdown
+files beside the boards that don't parse as one. These are warnings, not errors: each describes a
+workspace that still works, just not the way its author probably meant it to.

package/docs/filtering-and-sorting.md

@@ -0,0 +1,218 @@
+# Filtering and Sorting
+
+Kanbn uses one shared filtering model and one shared sorting model. They are used by:
+
+| Feature | Filters | Sorters |
+| --- | --- | --- |
+| `kanbn find` | yes (CLI options) | no |
+| `kanbn sort` | no | yes (CLI options) |
+| `columnSorting` project option | no | yes |
+| [Views](views.md) (root, column and lane filters) | yes | yes (per view column) |
+
+`kanbn status`, `kanbn burndown`, `kanbn gantt` and `kanbn history` have their own simpler `--column` / `--assigned` / `--date` / `--sprint` options and don't use this model.
+
+## Filters
+
+A filter set is a map of field names to filter values. **A task must match every filter in the set** (filters are combined with AND). An empty filter set matches all tasks.
+
+On the command line each `kanbn find` option is one filter. In the index options a filter set is a YAML object:
+
+```yaml
+filters:
+  column: 'In Progress'
+  tag: Bug
+  workload:
+    - 3
+    - 8
+```
+
+### Filter fields
+
+| Field | `kanbn find` option | Type | Matched against |
+| --- | --- | --- | --- |
+| `id` | `--id` | string | The task id (the task filename without `.md`) |
+| `name` | `--name`, `-n` | string | The task name (level-1 heading) |
+| `description` | `--description`, `-d` | string | The task description |
+| `column` | `--column`, `-c` | string | The name of the column the task is currently in |
+| `created` | `--created` | date | `created` metadata |
+| `updated` | `--updated` | date | `updated` metadata |
+| `started` | `--started` | date | `started` metadata |
+| `completed` | `--completed` | date | `completed` metadata |
+| `due` | `--due`, `-e` | date | `due` metadata |
+| `plannedStart` | `--plannedStart` | date | `plannedStart` metadata |
+| `plannedFinish` | `--plannedFinish` | date | `plannedFinish` metadata |
+| `assigned` | `--assigned` | string | `assigned` metadata (empty string if unset) |
+| `workload` | `--workload` | number | The task's [calculated workload](index-structure.md#taskworkloadtags) |
+| `progress` | `--progress` | number | The task's [calculated progress](task-structure.md#progress) |
+| `sub-task` | `--sub-task`, `-s` | string | All sub-tasks, one per line, as `[ ] text` or `[x] text` |
+| `count-sub-tasks` | `--count-sub-tasks` | number | Number of sub-tasks |
+| `tag` | `--tag`, `-t` | string | All tags, one per line |
+| `count-tags` | `--count-tags` | number | Number of tags |
+| `relation` | `--relation`, `-r` | string | All relations, one per line, as `type task-id` |
+| `count-relations` | `--count-relations` | number | Number of relations |
+| `comment` | `--comment` | string | All comments, one per line, as `author text` |
+| `count-comments` | `--count-comments` | number | Number of comments |
+| *custom field name* | `--<custom field name>` | declared type | The custom field value in the task metadata |
+
+Custom fields must be declared in the [`customFields`](index-structure.md#customfields) project option before they can be filtered on.
+
+A task that doesn't have the metadata field being filtered on never matches a date filter or a custom field filter. Missing `assigned` is treated as an empty string, missing `tags`/sub-tasks/relations/comments are treated as empty.
+
+*Note: `hiddenColumns` only affects the board. `kanbn find` still returns tasks in hidden columns unless you filter them out with `column`.*
+
+### String filters
+
+String filter values are **case-insensitive regular expressions**, matched anywhere in the value (not anchored). Passing an array (or repeating a CLI option) joins the values with `|`, so an array means "match any of these":
+
+```bash
+kanbn find --column Todo --column "In Progress"
+```
+
+```yaml
+filters:
+  column:
+    - Todo
+    - 'In Progress'
+```
+
+Multi-value fields (`tag`, `sub-task`, `relation`, `comment`) are flattened into a single newline-separated string before matching. The regex is **not** built with the multiline flag, so `^` and `$` anchor to the start and end of that whole string, not to each line. To match a single value exactly, anchor on the line breaks instead:
+
+```bash
+# Matches "Bug", but also "Debug" and "Bugfix"
+kanbn find --tag Bug
+
+# Matches only the exact tag "Bug"
+kanbn find --tag '(^|\n)Bug($|\n)'
+```
+
+### Date filters
+
+A single date matches any task whose date falls on **the same calendar day** — the time part is ignored:
+
+```bash
+kanbn find --due "20 July 2026"
+```
+
+Two or more dates match any task whose date falls **between the earliest and latest** of them (inclusive, times included):
+
+```bash
+kanbn find --due "1 July 2026" --due "31 July 2026"
+```
+
+On the command line dates are parsed with [chrono](https://github.com/wanasit/chrono), so almost any format works, including relative dates like `"yesterday"` or `"next friday"`. In YAML, write dates as plain YAML timestamps:
+
+```yaml
+filters:
+  due:
+    - 2026-07-01
+    - 2026-07-31
+```
+
+### Number filters
+
+A single number matches that number exactly. Two or more numbers match anything between the lowest and highest (inclusive):
+
+```bash
+kanbn find --workload 5              # exactly 5
+kanbn find --workload 3 --workload 8 # between 3 and 8
+```
+
+### Boolean filters
+
+Boolean filters only apply to custom fields with type `boolean`, and are matched by exact equality. On the command line, `--<name>` matches `true` and `--no-<name>` matches `false`:
+
+```bash
+kanbn find --needsDesign     # tasks where needsDesign is true
+kanbn find --no-needsDesign  # tasks where needsDesign is false
+```
+
+## Sorters
+
+A sorter list is an ordered array. Tasks are compared using the first sorter; ties are broken using the next one, and so on. Each sorter is an object:
+
+```yaml
+sorters:
+  - field: workload
+    order: descending
+  - field: name
+    filter: ''
+    order: ascending
+```
+
+| Property | Required | Description |
+| --- | --- | --- |
+| `field` | yes | The task field to sort by |
+| `order` | no | `ascending` (default) or `descending` |
+| `filter` | no | A regex used to transform values before comparing them (see below) |
+
+Strings are compared with `localeCompare` (accent-sensitive, case-insensitive); dates and numbers are compared numerically.
+
+### Sort filters
+
+The `filter` property is **not** a search filter — it extracts part of each value before comparing. The regex is applied globally and case-insensitively, and:
+
+- if it has named capturing groups, the contents of all named groups are concatenated;
+- otherwise, if it has numbered capturing groups, the contents of the first group are used;
+- otherwise, the whole match is used;
+- if there are multiple matches, their results are concatenated.
+
+```bash
+# Sort by the number in task names like "Task 12", not by the whole name
+kanbn sort "Todo" --name "Task (\d+)"
+```
+
+### Sortable fields
+
+`kanbn sort` and `columnSorting` can sort by any of these. Note that the `field` value written in YAML is **not** always the same as the command line option:
+
+| `field` value | `kanbn sort` option |
+| --- | --- |
+| `id` | `--id` |
+| `name` | `--name`, `-n` |
+| `description` | `--description`, `-d` |
+| `created` | `--created` |
+| `updated` | `--updated` |
+| `started` | `--started` |
+| `completed` | `--completed` |
+| `due` | `--due`, `-e` |
+| `plannedStart` | `--plannedStart` |
+| `plannedFinish` | `--plannedFinish` |
+| `assigned` | `--assigned` |
+| `workload` | `--workload`, `-w` |
+| `progress` | `--progress` |
+| `subTasks` | `--sub-task`, `-s` |
+| `countSubTasks` | `--count-sub-tasks` |
+| `tags` | `--tag`, `-t` |
+| `countTags` | `--count-tags` |
+| `relations` | `--relation`, `-r` |
+| `countRelations` | `--count-relations` |
+| `comments` | `--comment` |
+| `countComments` | `--count-comments` |
+| *custom field name* | `--<custom field name>` |
+
+[View](views.md) column `sorters` accept all of the same fields, plus `column` (the index column the task is currently in), which is useful in a view whose columns don't map onto index columns.
+
+A view sorter only changes the order within that view. To order a column permanently, use `columnSorting` — that ordering is written to the index itself, and view columns with no `sorters` of their own inherit it.
+
+## Persistent column sorting
+
+`columnSorting` keeps a column sorted in the index file itself, so the order survives `kanbn add`, `kanbn move` and `kanbn validate --save`:
+
+```yaml
+columnSorting:
+  Backlog:
+    - field: workload
+      order: descending
+    - field: name
+      order: ascending
+```
+
+You can also write this from the command line:
+
+```bash
+kanbn sort "Backlog" --workload -z --name -a --save
+```
+
+Running `kanbn sort "Backlog"` **without** `--save` removes any saved sorting settings for that column after applying the sort once.
+
+See `kanbn find --help` and `kanbn sort --help` for the full list of command line options, and [Views](views.md) for filters and sorters inside board views.