Files
worklane/docs/cli-arguments.md

7.9 KiB

The Command Line Surface

How arguments are defined and validated, and how the listing is filtered.

CLI Arguments

  • The prose arguments carry allow_hyphen_values, via the PROSE constant in command.rs: add --title, --description, --acceptance, --plan, and the comment body. Ticket text quotes flag names constantly, and without it a criterion reading --print is supported is parsed as a flag and the whole ticket is refused with nothing written
  • The trade: on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why due, priority, tags, owner and status are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add PROSE to a new argument unless it holds prose
  • --due is validated at parse time by iso_date, the way --priority is by priority_level. A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars without PROSE. One parser serves add and set: the field has one definition of what it accepts, and validating only add would leave set open, which is the command a grooming sweep actually uses
  • The shape is checked before chrono is asked. %Y-%m-%d accepts an unpadded 2026-8-9, which would be stored exactly as typed and sort before 2026-10-01 in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting
  • Strict on the way in, tolerant on the way out. util::due_date still cuts 2026-12-31T09:30:00Z down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
  • An empty --due keeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it
  • campaign add --codename is validated at parse time by codename, which is non_empty plus one word. The board draws it as a label with a mark and no quoting, so ~beaver release on that row reads as two labels and the second one is not a campaign; a title is where a sentence goes. Nothing else is checked: there is no registry of codenames, the same reason ls --tag refuses to validate a tag, and a length limit would be a number invented in the parser when the row that draws it already drops a label it cannot hold
  • There are two empty-value parsers, and which one an argument takes is the point. non_empty says only that the value cannot be empty, for the arguments with no empty form: the ls filters, relate's targets, and set --title, which addresses the ticket and names its file. clearable names --clear, for the arguments whose field does have one: set --tags, --due through iso_date, and the chown user. One message for both would either lie about ls --tag or leave the useful half unsaid. add --due takes the second one because iso_date is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser. append --tags is the one place the field has an empty form and the argument still takes non_empty: append has no --clear of its own, so naming one would send the caller looking on this command for a flag that is set's
  • A status is a util::Status, not a string. mv --status and the ls positional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain --due and --priority take, and it is what lets the shells complete the four for free. Status::ALL is the flow order, which status_dirs() and cmd_mv both read rather than spelling the names again, and DONE is defined from it
  • The ticket positionals (show <id>, mv <ticket>, comment <ticket>) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with --, as in mv --status committed -- -leading-title
  • A bare -- is a value when it follows an option (--title -- stores --) and clap's end-of-options marker when it sits in a positional. So a comment body of exactly -- needs its own separator, comment <ticket> -- --. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
  • add has no positionals, so anything after a bare -- is an unexpected argument and fails
  • A paragraph break in a description is an empty --description value. cmd_add joins the values with a single newline, so -d "First." -d "" -d "Second." writes the blank line. trim_blank_ends() drops blank values at either end, so a break never lands against a section heading, and an all-blank description reads as no description. Interior runs are kept verbatim rather than collapsed
  • --acceptance and --plan are lists, one criterium or step per value, so a blank there is spacing rather than content and the opencode wrapper drops it. Only --description preserves blanks

Filtering the Listing

  • The filters are one call, filtered, because ls collects a column in three places (a named status, the counts, and the grouped listing) and three call sites are three chances to apply a different set. Every filter is an Option and none asked for keeps everything, which is what makes them compose in any combination without a rule per pair
  • --tag matches whole values, not the field. parse_tags has already split the comma-separated field, so the filter compares against those trimmed values: --tag bug is not answered by a ticket tagged bugfix, and --tag "cli, filter" matches nothing, because the field as written is not itself a tag. A ticket with no tags matches none
  • Case sensitive, the opinion the field already takes: tag_color draws Bug and bug in two colours because they are two tags. A filter that folded them would list tickets carrying a tag nobody asked for, and would hide exactly the split a grooming sweep is looking for
  • One tag per invocation. Several would have to decide between and and or, and neither reading is obviously right for a board this size. That decision is its own ticket, along with a substring or regex match and a tag filter on the tui
  • A tag nothing carries lists nothing rather than being refused, which is the opposite of --campaign. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have. assets/PLAN.md tells the agent to check the spelling when a listing comes back empty, and worklane tags is what it checks against, since that is the failure this trades for
  • An emptied status keeps the message ls already gives, No tickets in '<status>' status., rather than one per filter naming what excluded them. That is pre-existing behaviour for --priority and --campaign, and one message for every filter is the consistent half of it. If it should name the filter, that is a change to what the CLI prints for three flags at once and belongs in its own ticket
  • cmd_ls takes an LsArgs, which is what the boundary in the Rust Style rule came to: four filters, an output mode and the directory, two of them adjacent Option<String> values a caller could swap silently. --ids was the argument that tipped it, the way add became AddArgs. A new filter is a field there, not a parameter