Command line

Generated

This page is the output of sprig --help and of each command’s help, from the build of crates/sprig-cli this site was built with. It cannot describe a flag the command does not have.

sprig

Plain-text plans for people and coding agents

Usage: sprig [OPTIONS] <COMMAND>

Commands:
  next      What can be done now: open, unblocked work, most urgent first
  check     Report broken grafts, loops and unknown references, for editors and CI
  fmt       Normalise indentation, write out typed dates, trim trailing space
  tick      Mark items done, or reopen them, or set any mark; a recurring item moves its due date
  tree      A plan as a tree, with progress, dates and what each item waits on; or the whole folder, a line per file
  why       Why an item is blocked, all the way down, with the file and line of each link
  find      Search items by text, @who, #tag, is:STATE and due:DATE
  export    The plans as data: the tree as JSON, dated work as iCalendar, items as CSV, the dependency graph for Graphviz or Mermaid
  import    Convert a Markdown checklist, a todo.txt file or GitHub issues to Sprig
  lsp       Run the language server on stdin and stdout, for editors
  mcp       Serve the plans to a coding agent over the Model Context Protocol, on stdin and stdout
  tui       Work the plan from one screen: the tree, next up and the agenda, with vim keys
  generate  Print a shell completion script, or the manual page in roff

Options:
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help
  -V, --version       Print version

Paths are .sprig files or directories; a directory means every .sprig file
under it. With no path, the current directory.

Exit codes:
  0  fine
  1  findings: `check` found errors (or warnings, with --strict), `next`
     found nothing ready, `find` matched nothing, or `fmt --check` found
     files to change
  2  usage error, or a path that could not be read

sprig next

What can be done now: open, unblocked work, most urgent first

What can be done now: open, unblocked work, most urgent first

Usage: sprig next [OPTIONS] [PATH]...

Arguments:
  [PATH]...  Plans to read

Options:
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --who <NAME>    Only work whose owner is NAME (with or without the @)
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --limit <N>     Show at most N items
      --json          Ready work as JSON: a ref, a path and a node of the tree format each
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help

Paths are .sprig files or directories; a directory means every .sprig file
under it. With no path, the current directory.

Exit codes:
  0  fine
  1  findings: `check` found errors (or warnings, with --strict), `next`
     found nothing ready, `find` matched nothing, or `fmt --check` found
     files to change
  2  usage error, or a path that could not be read

sprig check

Report broken grafts, loops and unknown references, for editors and CI

Report broken grafts, loops and unknown references, for editors and CI

Usage: sprig check [OPTIONS] [PATH]...

Arguments:
  [PATH]...  Plans to read

Options:
      --strict        Exit 1 on warnings too
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --json          Diagnostics as JSON, in the tree format's shape; the exit code is the same
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help

Paths are .sprig files or directories; a directory means every .sprig file
under it. With no path, the current directory.

Exit codes:
  0  fine
  1  findings: `check` found errors (or warnings, with --strict), `next`
     found nothing ready, `find` matched nothing, or `fmt --check` found
     files to change
  2  usage error, or a path that could not be read

sprig fmt

Normalise indentation, write out typed dates, trim trailing space

Normalise indentation, write out typed dates, trim trailing space

Usage: sprig fmt [OPTIONS] [PATH]...

Arguments:
  [PATH]...  Plans to format

Options:
      --check         Write nothing; list the files that would change, and exit 1 if any
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help

Paths are .sprig files or directories; a directory means every .sprig file
under it. With no path, the current directory.

Exit codes:
  0  fine
  1  findings: `check` found errors (or warnings, with --strict), `next`
     found nothing ready, `find` matched nothing, or `fmt --check` found
     files to change
  2  usage error, or a path that could not be read

sprig tick

Mark items done, or reopen them, or set any mark; a recurring item moves its due date

Mark items done, or reopen them, or set any mark; a recurring item moves its due date

Usage: sprig tick [OPTIONS] <REF>...

Arguments:
  <REF>...  Items to tick

Options:
      --in <PATH>     The plans the refs are in [default: .]
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --mark <MARK>   Set this mark instead: - ~ x / > or ?, or todo, doing, done, dropped, later, ask
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help

Ticking an item done marks it x, and ticking a done item reopens it. --mark
sets any status mark instead: - ~ x / > or ?. Everything else is a change to
the file, made in an editor: the file is the truth.

A ref names one item, from exact to forgiving:
  ^signed          an anchor, in any file
  lease^signed     an anchor in one file
  lease.sprig:13   the item on a line, as compilers print it
  "grease trap"    words from the item's text, matching one item
  -                refs from standard input, one per line

Every ref is resolved before anything is written: if one is unknown or
ambiguous, nothing changes, the candidates are listed, and the exit code is 2.

Exit codes:
  0  ticked
  2  usage error, a ref that names no item or several, an item that cannot
     take the mark, or a path that could not be read or written

sprig tree

A plan as a tree, with progress, dates and what each item waits on; or the whole folder, a line per file

A plan as a tree, with progress, dates and what each item waits on; or the whole folder, a line per file

Usage: sprig tree [OPTIONS] [PATH]...

Arguments:
  [PATH]...  Plans to show

Options:
      --depth <N>     Show N levels at most
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --hide-done     Leave out done and dropped items
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
      --summary       The whole folder on one screen: a line per file with its progress, and what is waiting and late
      --oneline       With --summary: one short line for a shell prompt or a status bar; exit 1 if anything is late
      --json          With --summary: a row per plan as JSON: file, title, done, total, ready, waiting, late and errors
  -h, --help          Print help

Paths are .sprig files or directories; a directory means every .sprig file
under it. With no path, the current directory.

Exit codes:
  0  fine
  1  findings: `check` found errors (or warnings, with --strict), `next`
     found nothing ready, `find` matched nothing, or `fmt --check` found
     files to change
  2  usage error, or a path that could not be read

sprig why

Why an item is blocked, all the way down, with the file and line of each link

Why an item is blocked, all the way down, with the file and line of each link

Usage: sprig why [OPTIONS] <REF>

Arguments:
  <REF>  The item to explain

Options:
      --in <PATH>     The plans the ref is in [default: .]
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help

Exit codes:
  0  the item is not blocked
  1  the item is blocked; the chain says by what
  2  usage error, or a ref that names no item or several

sprig find

Search items by text, @who, #tag, is:STATE and due:DATE

Search items by text, @who, #tag, is:STATE and due:DATE

Usage: sprig find [OPTIONS] <QUERY>...

Arguments:
  <QUERY>...  Words and filters

Options:
      --in <PATH>     The plans to search [default: .]
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --json          Matches as JSON: a ref, a path and a node of the tree format each
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help

A query is words and filters, all of which an item must match:
  oven               words from the item's text, ignoring case
  @teo  #kitchen     its people (inherited ones included) and its tags
  is:open            open, todo, doing, done, dropped, later, ask or blocked
  due:<fri           its own due date: <, <=, >, >= or exactly, as a date
                     or a shortcut such as fri, +2w or oct3

Exit codes:
  0  something matched
  1  nothing matched
  2  usage error, an unknown filter, or a path that could not be read

sprig export

The plans as data: the tree as JSON, dated work as iCalendar, items as CSV, the dependency graph for Graphviz or Mermaid

The plans as data: the tree as JSON, dated work as iCalendar, items as CSV, the dependency graph for Graphviz or Mermaid

Usage: sprig export [OPTIONS] --format <FORMAT> [PATH]...

Arguments:
  [PATH]...
          Plans to read

Options:
      --format <FORMAT>
          What to write

          Possible values:
          - json:    Each plan's tree, in the tree format (spec Appendix D)
          - ics:     An all-day event per dated item, for a calendar to subscribe to
          - csv:     Every item, one row each
          - dot:     The dependency graph, for Graphviz
          - mermaid: The dependency graph, for Mermaid

      --today <DATE>
          The date to answer for, as YYYY-MM-DD [default: the system date]

          [env: SPRIG_TODAY]

      --color <WHEN>
          When to colour the marks [default: auto, which is off when NO_COLOR is set]

          [possible values: auto, always, never]

      --plain
          Tab-separated output for scripts: a ref first, no colour, nothing cut

  -h, --help
          Print help (see a summary with '-h')

Paths are .sprig files or directories; a directory means every .sprig file
under it. With no path, the current directory.

Exit codes:
  0  fine
  1  findings: `check` found errors (or warnings, with --strict), `next`
     found nothing ready, `find` matched nothing, or `fmt --check` found
     files to change
  2  usage error, or a path that could not be read

sprig import

Convert a Markdown checklist, a todo.txt file or GitHub issues to Sprig

Convert a Markdown checklist, a todo.txt file or GitHub issues to Sprig

Usage: sprig import [OPTIONS] <FILE>

Arguments:
  <FILE>  The file to convert, or - for standard input

Options:
      --from <FROM>   The file's format [default: from its extension] [possible values: markdown, todotxt, github]
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --title <TEXT>  The title for a format that has none [default: from the file name]
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help

The format comes from the file's extension unless --from names it: .md is a
Markdown checklist, .txt is todo.txt, and .json is the output of
  gh issue list --json number,title,state,labels,assignees,milestone
The Sprig file is printed; redirect it where it belongs. Nothing is read from
the network.

Exit codes:
  0  converted
  2  usage error, or a file that could not be read or understood

sprig lsp

Run the language server on stdin and stdout, for editors

Run the language server on stdin and stdout, for editors

Usage: sprig lsp [OPTIONS]

Options:
      --today <DATE>  The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>  When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --plain         Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help          Print help

sprig mcp

Serve the plans to a coding agent over the Model Context Protocol, on stdin and stdout

Serve the plans to a coding agent over the Model Context Protocol, on stdin and stdout

Usage: sprig mcp [OPTIONS]

Options:
      --in <PATH>          The folder of plans to serve [default: .]
      --today <DATE>       The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>       When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --max-new-items <N>  The most items add_items may add, in one call and in the whole session [default: 20]
      --config             Print the configuration that registers this server with an MCP client, and exit
      --plain              Tab-separated output for scripts: a ref first, no colour, nothing cut
      --instructions       Print the instructions that tell a coding agent how this repository plans, and exit
      --write <FILE>       With --instructions: keep them in FILE, such as AGENTS.md or CLAUDE.md, between markers; a second run replaces the block, and changes nothing if it is current
  -h, --help               Print help

Register it with an agent's MCP client; `sprig mcp --config` prints the
snippet, and `sprig mcp --instructions --write AGENTS.md` tells the agent how
the repository plans. Tools: list_plans, show_tree, next_items, find_items, check_plans,
tick_items, mark_item, add_items, answer_question and set_field.

Every write goes through the same edit API as `sprig tick`, is refused when it
would add an error `sprig check` reports, and returns the diff it applied.

sprig tui

Work the plan from one screen: the tree, next up and the agenda, with vim keys

Work the plan from one screen: the tree, next up and the agenda, with vim keys

Usage: sprig tui [OPTIONS] [PATH]

Arguments:
  [PATH]  A plan or a folder of plans [default: .]

Options:
      --screenshot <WxH>  Print one frame, WIDTHxHEIGHT such as 100x30, as text and exit
      --today <DATE>      The date to answer for, as YYYY-MM-DD [default: the system date] [env: SPRIG_TODAY]
      --color <WHEN>      When to colour the marks [default: auto, which is off when NO_COLOR is set] [possible values: auto, always, never]
      --keys <KEYS>       With --screenshot: keys to press first, such as "jjx" or "/oven<Enter>"
      --plain             Tab-separated output for scripts: a ref first, no colour, nothing cut
  -h, --help              Print help

Keys: j k move, h l fold, x tick, ~ doing, a A add, e edit, u undo,
1 2 3 tree, next up and agenda, / filter, ? help, q quit.

Every write goes through the same edit API as `sprig tick`, and is refused if
the line changed on disk since the TUI read it. The files are read again
whenever one changes.

sprig generate

Print a shell completion script, or the manual page in roff

Print a shell completion script, or the manual page in roff

Usage: sprig generate [OPTIONS] <WHAT>

Arguments:
  <WHAT>
          A shell to complete for, or man for the manual page

          Possible values:
          - bash:       A completion script for bash
          - zsh:        A completion script for zsh
          - fish:       A completion script for fish
          - elvish:     A completion script for elvish
          - powershell: A completion script for PowerShell
          - man:        The manual page, in roff

Options:
      --today <DATE>
          The date to answer for, as YYYY-MM-DD [default: the system date]

          [env: SPRIG_TODAY]

      --color <WHEN>
          When to colour the marks [default: auto, which is off when NO_COLOR is set]

          [possible values: auto, always, never]

      --plain
          Tab-separated output for scripts: a ref first, no colour, nothing cut

  -h, --help
          Print help (see a summary with '-h')