Enum Command 

pub enum Command {
    Init {
        beads: Option<String>,
    },
    InitAgents {
        yes: bool,
    },
    Version,
    Beads {
        action: BeadsAction,
    },
    Create {

        title: Option<String>,
        body: Option<String>,
        status: Option<String>,
        priority: Option<String>,
        assignee: Option<String>,
        labels: Option<String>,
        files: Option<String>,
        estimate: Option<String>,
        cycles: Option<String>,
        milestones: Option<String>,
        projects: Option<String>,
        epics: Option<String>,
        reviewer: Option<String>,
        start_date: Option<String>,
        due_date: Option<String>,
        parent: Option<String>,
        related_issues: Option<String>,
        type: Option<String>,
        template: Option<String>,
        scope: Option<String>,
    
},
    Link {
        action: Option<LinkAction>,
        from: Option<String>,
        to: Option<String>,
        type: Option<String>,
    },
    Bulk {
        action: BulkAction,
    },
    Unlink {
        from: String,
        to: String,
        type: Option<String>,
    },
    Chain {
        issue: String,
    },
    Parent {
        action: ParentAction,
    },
    Edit {

        issue: String,
        title: Option<String>,
        body: Option<String>,
        status: Option<String>,
        priority: Option<String>,
        assignee: Option<String>,
        labels: Option<String>,
        files: Option<String>,
        estimate: Option<String>,
        cycles: Option<String>,
        milestones: Option<String>,
        add_project: Vec<String>,
        remove_project: Vec<String>,
        projects: Option<String>,
        add_epic: Vec<String>,
        remove_epic: Vec<String>,
        epics: Option<String>,
        reviewer: Option<String>,
        start_date: Option<String>,
        due_date: Option<String>,
        commit: Option<String>,
        parent: Option<String>,
        reason: Option<String>,
        related_issues: Option<String>,
        type: Option<String>,
    
},
    Move {
        args: Vec<String>,
        select: Option<String>,
        filter: Option<String>,
        search: Option<String>,
        dry_run: bool,
        commit: Option<String>,
        reason: Option<String>,
        yes: bool,
        override: bool,
    },
    Wip {
        action: WipAction,
    },
    View {
        action: Option<ViewAction>,
        issue: Option<String>,
        show: Option<String>,
    },
    Recurring {
        action: RecurringAction,
    },
    List {
        status: Option<String>,
        filter: Option<String>,
        project: Option<String>,
        epic: Option<String>,
        with_archived: bool,
        sort: Option<String>,
        group: Option<String>,
        columns: Option<String>,
        show: Option<String>,
        all: bool,
        format: Option<String>,
    },
    Ready {
        columns: Option<String>,
        limit: Option<usize>,
        project: Option<String>,
        epic: Option<String>,
        format: Option<String>,
    },
    Workflow {
        action: WorkflowAction,
    },
    Status {
        filter: Option<String>,
        sort: Option<String>,
        group: Option<String>,
        health: bool,
        json: bool,
    },
    Health {
        action: HealthAction,
    },
    Mentions {
        action: MentionsAction,
    },
    Triage {
        action: TriageAction,
    },
    Delete {
        issue: String,
        yes: bool,
    },
    Archive {
        issues: Vec<String>,
    },
    Restore {
        issues: Vec<String>,
    },
    Cycle {
        command: CycleCommand,
    },
    Capacity {
        command: CapacityCommand,
    },
    Time {
        command: TimeCommand,
    },
    Milestone {
        command: MilestoneCommand,
    },
    Project {
        command: ProjectCommand,
    },
    Epic {
        command: EpicCommand,
    },
    Initiative {
        command: InitiativeCommand,
    },
    Roadmap {
        command: RoadmapCommand,
    },
    Analytics {
        command: AnalyticsCommand,
    },
    Export {
        target: String,
        dry_run: bool,
        project: Option<String>,
        cycle: Option<String>,
        output: Option<String>,
        verbose: bool,
    },
    Import {
        target: String,
        triage_policy: Option<String>,
    },
    Rollover {
        cycle: Option<String>,
        yes: bool,
    },
    Search {
        string: String,
        with_archived: bool,
    },
    Render,
    Clean {
        force: bool,
        keep: usize,
    },
    New,
    Lint {
        no_foreign: bool,
    },
    Layout {
        action: LayoutAction,
    },
    Migrate {
        action: MigrateAction,
    },
    Mcp,
    Template {
        action: TemplateAction,
    },
}

Variants

Init

Create a default tix.toml ([kanban.default], issues_dir, [export]).

When bd is on PATH and a beads workspace is reachable, an interactive run also offers the beads modes; --beads decides without a prompt, and a non-interactive run never prompts (it keeps off unless --beads says otherwise).

Fields

beads: Option<String>

Beads mode to record: off | mirror | sync

mirror reads a beads workspace through bd for viewing only; sync installs the .beads/hooks that pull beads changes into tix.

InitAgents

Append or replace the tix block in AGENTS.md (idempotent)

Fields

yes: bool

Overwrite an outdated block without prompting

Version

Print the crate version and how this binary was built

Answers the question --version cannot: whether the binary on disk came from the source on disk. It reports the commit it was built from and when, so a rebuild that did not happen is visible. Needs no tix.toml, so it works in any directory.

Beads

Read, or write, a beads workspace through the bd CLI

tix never opens the beads Dolt database: every verb here shells out to bd. The reads (detect, status, list, show, watch) write nothing anywhere; the writes (push, pull, reconcile) are refused while the beads mode is mirror, which is read-only by contract. See docs/for-users/beads-integration.md.

Fields

action: BeadsAction

Create

Create an issue

Fields

title: Option<String>

Issue title (prompted when missing on a TTY)

body: Option<String>

Issue body (markdown)

status: Option<String>

Column name (default: first column)

priority: Option<String>

Priority: low | medium | high (default medium)

assignee: Option<String>

Assignee (@name)

labels: Option<String>

Labels, comma-separated

files: Option<String>

Files governing this issue, comma-separated

estimate: Option<String>

Estimate

cycles: Option<String>

Cycle names, comma-separated

milestones: Option<String>

Milestone names, comma-separated

projects: Option<String>

Projects to associate the new issue with: ids or names, comma-separated

Every reference is resolved through the project service before the issue is written, so an unknown id refuses the whole create rather than leaving a half-associated issue. This flag lives on the shared create path, which is the handoff point a future template surface (source issue #174) would populate (mission first-class-projects-01M3BYBW).

epics: Option<String>

Epics the new issue references: ids or names, comma-separated

Every reference is resolved through the epic service before the issue is written, so an unknown id refuses the whole create rather than leaving a half-referenced issue. This flag lives on the shared create path, which is the handoff point a future template surface (source issue #174) would populate. Referencing an epic never changes how the issue itself is navigated: it stays an ordinary issue (mission epics-work-items-01M3BYW4).

reviewer: Option<String>

Reviewer (free-form name/identity)

start_date: Option<String>

Start date (YYYY-MM-DD)

due_date: Option<String>

Due date (YYYY-MM-DD); must be >= start_date

parent: Option<String>

Create as a child of this issue (number, filename or title fragment)

At most one parent, so this takes a single selector and there is no list form (C-001). The parent must already exist; a selector that matches no issue is refused and nothing is created.

related_issues: Option<String>

Related issues, comma-separated: a local number/selector, a relative or absolute path to another issue file, or a repository URL (host/path#id). Free-form; stored verbatim.

type: Option<String>

Issue type (e.g. bug, feature); tix lint warns on a value not in custom_types.

template: Option<String>

Create from a stable template ID (tix template list)

The template’s defaults and prompts are merged with the flags above by the pure resolver, then the resolved request goes through the shared create core — there is no second issue writer. Resolution never prompts: a required prompt with no value is a diagnostic, the template and the store are left untouched, and no issue is written.

scope: Option<String>

Template scope: repository | board:<name> | team:<label>

Only meaningful with --template (clap requires it). An omitted scope is the explicit repository default, never an implicit inheritance. The selected template ID and scope are echoed on stderr so stdout keeps the Created <file> shape.

Link

Create, edit, remove, or list typed relationships

Creating requires --type; there is no default kind, so an untyped relationship is never recorded by accident (C-001). Omit the subcommand to create: tix link <from> <to> --type <kind>.

Fields

action: Option<LinkAction>

edit, remove, or list. Omit to create a relationship.

These three words are reserved on tix link: an issue whose number, filename, or title selector is exactly edit, remove, or list must be addressed by number.

from: Option<String>

[create] Issue number, filename fragment or unique title fragment

to: Option<String>

[create] Issue number, filename fragment or unique title fragment

type: Option<String>

[create] Relationship kind: blocks, blocked_by, duplicates, related

Bulk

Batch editing over a selection

Preview is the default; --apply writes. Name exactly one of --select, --filter or --search — they are different grammars, and a bulk operation will not guess which issues you meant.

Fields

action: BulkAction

Unlink

Remove a typed relationship between two issues

Fields

from: String

Issue number, filename fragment or unique title fragment

to: String

Issue number, filename fragment or unique title fragment

type: Option<String>

Relationship kind: blocks, blocked_by, duplicates, related

Chain

Print the transitive dependency chain an issue holds up

Fields

issue: String

Issue number, filename fragment or unique title fragment

Parent

Inspect the issue hierarchy

show, children, or list. Every figure comes from the hierarchy service’s typed values, so the CLI, the TUI detail block and the MCP read tools report the same numbers for the same issue.

Fields

action: ParentAction

show, children, or list

Edit

Edit an issue

Fields

issue: String

Issue number, filename fragment or unique title fragment

title: Option<String>

New title

body: Option<String>

New body (markdown)

status: Option<String>

New status

Setting the status is a move, validated by the same service as tix mv and recorded as the same TransitionDecision — it is not a way around the transition policy. --status "" clears the field (matching every other field here) and is a plain field write, not a transition, because there is no target column to judge.

priority: Option<String>

New priority: low | medium | high

assignee: Option<String>

New assignee (@name)

labels: Option<String>

New label list, comma-separated

files: Option<String>

New files list, comma-separated

estimate: Option<String>

New estimate: 3, 3d, 1 day, 0.5-1 day, 3 weeks 2 hours (empty clears)

cycles: Option<String>

New cycle list, comma-separated (--cycles "" clears)

milestones: Option<String>

New milestone list, comma-separated (--milestones "" clears)

add_project: Vec<String>

Associate the issue with a project (id or name); repeatable

Idempotent: an already-present association is a no-op with no History entry. The reference is resolved through the project service before anything is written, so an unknown project refuses the edit and leaves the file byte-identical.

remove_project: Vec<String>

Dissociate the issue from a project (id or name); repeatable

Drops only the association — the issue is never deleted. A known project that is not associated is a no-op; an unresolvable reference that the issue does not carry is refused as unknown_project.

projects: Option<String>

Replace the whole association list, comma-separated

Only a blank value is accepted here: --projects "" clears every association, mirroring the empty-string-clears convention the other list flags follow. To add or drop individual associations use --add-project / --remove-project; a non-blank value is refused rather than guessed at.

add_epic: Vec<String>

Add an epic reference (id or name); repeatable

Idempotent: an already-present reference is a no-op with no History entry. The reference is resolved through the epic service before anything is written, so an unknown epic refuses the edit and leaves the file byte-identical.

remove_epic: Vec<String>

Remove an epic reference; repeatable

Drops only the reference — the issue is never deleted. A known epic that is not referenced is a no-op; an unresolvable reference the issue does not carry is refused as unknown_epic. A retained stale id can still be removed by naming it verbatim.

epics: Option<String>

Clear every epic reference

Only a blank value is accepted here: --epics "" clears every reference, mirroring the empty-string-clears convention --projects follows. To add or drop individual references use --add-epic / --remove-epic; a non-blank value is refused rather than guessed at.

reviewer: Option<String>

New reviewer (--reviewer "" clears)

start_date: Option<String>

New start date (YYYY-MM-DD; --start-date "" clears)

due_date: Option<String>

New due date (YYYY-MM-DD; --due-date "" clears)

commit: Option<String>

Commit hash to record (auto resolves it from git history, clear removes it)

parent: Option<String>

Set or change the parent (number, filename or title fragment)

--parent "" clears the parent, mirroring --assignee ""; omitting the flag leaves it untouched. Validated before any write, so a self-parent, an unknown parent, or a change that would close a cycle leaves the file byte-identical.

reason: Option<String>

Why a transition policy is being overridden by --status

--status is validated exactly as tix mv is, so moving an issue out of a terminal category needs the same reasoned override, and the reason is recorded in the same History decision. --status deliberately has no --yes: acknowledging blockers is spelled tix move … --yes, and giving this flag a second spelling would give the audit trail two.

related_issues: Option<String>

New related-issues list, comma-separated (--related-issues "" clears). A local number/selector, a relative or absolute path to another issue file, or a repository URL (host/path#id).

type: Option<String>

New issue type (--type "" clears it); tix lint warns on a value not in custom_types.

Move

Move one or more issues to a column

A single selector behaves exactly as before. More than one position, --select, --filter or --search moves the whole selection; a batch larger than one requires --yes to apply, and --dry-run previews it.

Fields

args: Vec<String>

Issue selectors followed by the target column. The last value is the column; the preceding ones are selectors (number, filename fragment, unique title fragment, comma- or space-separated).

select: Option<String>

Comma-separated issue selectors (same grammar as the positional list)

filter: Option<String>

A --filter query, in the existing filter grammar

search: Option<String>

A --search query, in the existing search grammar

dry_run: bool

Print the batch plan and write nothing

commit: Option<String>

Commit hash to record when moving to a completion column (auto resolves it from git history; omitted, the current HEAD is captured automatically)

“Completion” is whatever the board’s category mapping calls completed — not a column literally named done. On a board with no [kanban.<name>.category_map] the board’s done_column is the completion column.

reason: Option<String>

Why a transition policy is being overridden

Required to move an issue out of a terminal category (completed or canceled) when the board declares a category_map. The reason is recorded in the issue’s History, so the audit trail explains itself later. A blank value is not a reason and is refused.

A board with no category_map has no transition policy to override: it keeps the completion definition and the commit rule, and moving out of done stays permitted.

yes: bool

Confirm without prompting

Also the acknowledgement a move toward the board’s completion column needs when the issue has open blockers. Without it that move is refused, and a recorded acknowledgement is appended to the issue’s History so the decision stays auditable.

For a selection larger than one, --yes is also the batch confirmation: without it the plan is printed and nothing is written.

override: bool

Authorize overriding a blocking work-in-progress limit

--override is a request, not an authorization. The move only proceeds when --reason states why and --yes confirms it, and the override is recorded — actor, timestamp, reason and the limit it was authorized against — as a History entry on the issue. Without --override a move that would exceed a block limit is refused and nothing is written; a warn limit never needs one.

Wip

Inspect or configure work-in-progress limits

Limits live in tix.toml under [kanban.<board>.wip]: a column’s ceilings (max_items, max_estimate), the unit an estimate ceiling counts in, and whether exceeding it warns or blocks. A board with no limits behaves exactly as it did before they existed.

Fields

action: WipAction

View

Print an issue, or manage saved views (#172)

tix view <issue> prints the issue file, unchanged. Without an issue selector the subcommands below manage repository-owned saved views: named, stable-ID query definitions with explicit scope metadata and a normalized plan over the existing filter/sort/group/visibility grammar.

The nine subcommand words (list, show, create, update, duplicate, delete, apply, status, share) are reserved on tix view: an issue whose selector is exactly one of them must be addressed by number, exactly as tix link reserves edit / remove / list.

Fields

action: Option<ViewAction>

list, show, create, update, duplicate, delete, apply, status, or share. Omit to print an issue.

issue: Option<String>

print Issue number, filename fragment or unique title fragment

show: Option<String>

print Extra information to append, comma-separated

relationships appends the service-derived relationship block, the transitive chain, and the blocked reason. Without it the issue file is printed verbatim, so tix view <n> > file still round-trips.

Recurring

Manage recurring issue series (tix #175)

A series is a normal issue that carries a series: table in its frontmatter: the issue holds the rule, the lifecycle state, and the template an occurrence is created from; each occurrence is another normal issue carrying the series id, the date and the idempotency key.

detect is read-only and reports what is due; generate and every lifecycle action need --yes, because no refresh, timer or detection may change a schedule on its own.

Fields

action: RecurringAction

List

One line per issue: number, id and title

The default listing is scoped: your issues (the git author identity, when it can be derived) in the board’s entry column — todo on the board tix init writes. --all drops the scope, and --status/--filter replace it. The title is cropped to the terminal’s width, so every issue occupies exactly one line; the full board is tix render.

Fields

status: Option<String>

Only issues in this status

filter: Option<String>

Token query (cycle:, milestone:, reviewer:, overdue, etc.)

project: Option<String>

Restrict the listing to one project (stable id, or a display name)

Resolved through the project service and applied through the shared project: criterion, so tix list --project <id> and tix search "project:<id>" return the same matching set.

epic: Option<String>

Restrict the listing to one epic (stable id, or a display name)

Resolved through the epic service and applied through the shared epic: criterion, so tix list --epic <id> and tix search "epic:<id>" return the same matching set. An unknown reference matches nothing, so a typo yields a visible empty listing rather than a silent unfiltered one.

with_archived: bool

Include archived issues, marked with an ARCHIVED column

Off by default, and off for a reason: archived issues are skipped without being read, so a repository with thousands of them lists fast.

sort: Option<String>

Sort key (created, due, start, reviewer, cycle, milestone, project, epic, status, priority)

group: Option<String>

Group key (cycle | milestone | project | epic)

columns: Option<String>

Comma-separated columns to display

The full set: num, id, title, status, priority, cycle, milestone, reviewer, start, due, overdue, blocked, relations, progress, projects, epics, category, archived, wip, health. The value_name used to list only the first ten, so a column this build had supported for two missions looked unsupported in --help; a column left out of this list is the same lie about a smaller set.

show: Option<String>

Extra information to include, comma-separated

relationships adds a relationship summary and a blocked marker per issue, read from the relationship service so the CLI and the TUI cannot disagree.

progress adds a parent rollup; category adds the issue’s resolved category label, read from the shared service so this surface and the TUI cannot spell one category two ways.

wip adds the column’s usage against its limit, and health adds the issue’s health (its own value, with the derived rollup beside it when the two differ), read from the one portable health document.

all: bool

List every issue, ignoring the default scope

The default listing is scoped to your issues in the board’s entry column. --all drops both halves of that scope — the listing is then every active issue, exactly as it was before the scope existed.

format: Option<String>

Emit a structured document instead of the table: xml, yml or toml

One record per issue, keyed by the columns being displayed, under the single root issues — so --columns chooses the fields. JSON is deliberately not one of them.

Ready

The next issue to start: unblocked, highest priority first

The tix list a working session opens with. It shows every issue that nothing blocks and that has not begun — a column the board maps to backlog or unstarted, no further along than the column new work lands in — ordered by priority (highest first, then oldest first), so the first row is the issue to pick up next. Blocked means an open blocker: the same graph the blocked column reads, so finishing a blocker returns its dependents here.

Fields

columns: Option<String>

Comma-separated columns to display

The default set is num,id,priority,title: the identity pair, the priority the list is ordered by, and the title.

limit: Option<usize>

Show at most this many issues

Applied after the ordering, so --limit 1 is the single next issue.

project: Option<String>

Restrict the listing to one project (stable id, or a display name)

epic: Option<String>

Restrict the listing to one epic (stable id, or a display name)

format: Option<String>

Emit a structured document instead of the table: xml, yml or toml

Workflow

Inspect the status-category vocabulary, a board’s mapping, and the effective transition policy

A read-only surface. It never writes and never repairs, so it is safe to run on a repository whose tix.toml is mid-edit.

Fields

action: WorkflowAction

Status

Board summary: count per column + total

Fields

filter: Option<String>

Token query (cycle:, milestone:, reviewer:, overdue, etc.)

sort: Option<String>

Sort key (created, due, start, reviewer, cycle, milestone, status, priority)

group: Option<String>

Group key (cycle | milestone | project | epic)

health: bool

Add the health summary: issue counts per state, with diagnostics

Read from the same portable health document tix health board and the TUI render, so the figures are the same figures. Off by default: the board summary is about columns, and health is metadata about the work (C-006).

json: bool

Print one machine-readable JSON object instead of the table

The object is the board summary: columns in board order, each with its count, and total. With --health the same health object MCP’s board_status returns is added; without it the key is absent. The table without this flag is unchanged.

Health

Project and issue health: read a scope, roll it up, or record a change

Health is metadata, not the board’s status: it never replaces a status category and never means “done”. The current value lives in an issue’s frontmatter, every change is an append-only History entry carrying an actor, a date and a rationale, and a scope’s derived value comes from what contributes to it under a versioned policy (health-v1).

set and override are the mutations, and both refuse — having written nothing — when an audit field is missing. show, rollup, history and board read.

Fields

action: HealthAction

Mentions

Read and act on your @mentions (issue-mentions)

A mention is @handle or @name@host in an issue’s title or body, recorded per mentioned target under docs/mentions/. This command is the non-interactive surface: it lists what is pending for you and applies the three answers without a prompt, so the flow works from a script and without a TTY. The TUI has the same three answers on the bottom indicator row’s chord.

Fields

action: MentionsAction

Triage

Triage the inbox: read-only queue views and the four decisions

Fields

action: TriageAction

Delete

Delete an issue file

Fields

issue: String

Issue number, filename fragment or unique title fragment

yes: bool

Confirm without prompting

Archive

Archive issue files: rename each in place to a dot-prefixed name

The default views (tix list, tix search) skip archived issues; pass their --with-archived flag or the archived:true filter to see them.

Fields

issues: Vec<String>

Issue numbers, filename fragments or unique title fragments

Restore

Restore archived issue files: the inverse of tix archive

Fields

issues: Vec<String>

Issue numbers, filename fragments or unique title fragments

Cycle

Manage planning cycles

Fields

command: CycleCommand

Capacity

Configure and inspect cycle, team and assignee capacity

A ceiling is a scope (one cycle, one team label, or one assignee identity) with a non-negative value in an estimate unit the active board declares. calculate reports the shared committed/completed/remaining/overflow/ utilization values and never mutates an issue; snapshot reads back the immutable evidence a cycle close captured.

Fields

command: CapacityCommand

Time

Record and review actual effort against issues, in whole minutes

A time entry is a duration, an optional YYYY-MM-DD calendar date, an author and an optional note — there is no timer, no timezone conversion and no overlap rule. Current entries live in the issue’s own frontmatter, every correction and deletion appends an attributable History event, and a deletion removes the current value only. add, edit and delete are the mutations (edit and delete require --reason; delete also requires --confirm), and show, history and total are reads whose numbers come from one shared calculation.

Fields

command: TimeCommand

Milestone

Manage milestones

Fields

command: MilestoneCommand

Project

Create, edit, list, inspect, delete and populate projects

A project is a stable id (a registry key in tix.toml) with a mutable display name. An issue carries project ids, so a rename breaks no association: the id is the identity and the name is a label. Every listing prints the id beside the name, because without it a rename is indistinguishable from a new project.

delete removes the registry entry only. The issues that referenced the project keep their references, which then read as diagnosable missing references (tix lint names each one), so nothing is destroyed by deleting a project and there is deliberately no --cascade and no bulk-delete of issues.

add, remove and bulk-add process each issue selector independently: a rejection on one selector is reported and never aborts the rest. Their scope is project association only — general bulk editing is a different feature.

Fields

command: ProjectCommand

Epic

Create, edit, list, inspect, navigate and delete epics; associate work items

An epic is a stable id (a registry key in tix.toml) with a mutable display name. A work item references epic ids, so a rename breaks no reference: the id is the identity and the name is a label. Every listing prints the id beside the name, because without it a rename is indistinguishable from a new epic.

A “task” is an ordinary issue: tix edit <sel> --labels task --add-epic <id> adds a reference to an issue. No task entity, file or frontmatter key is created, and direct issue navigation stays available from every view.

delete removes the registry entry only. The issues that referenced the epic keep their references (which then read as missing references) and the child epics keep their recorded parent (which then reads as unresolved), so nothing is destroyed by deleting an epic and there is deliberately no --cascade.

add, remove and bulk-add process each issue selector independently: a rejection on one selector is reported and never aborts the rest. Their scope is epic reference only — general bulk editing is a different feature.

Fields

command: EpicCommand

Initiative

Create, edit, list, inspect, delete and associate roadmap initiatives

An initiative is a stable id (a registry key in tix.toml) with a mutable display name, an optional target date/status/owner, and explicit project/epic/milestone associations. The id is the identity, so a rename breaks no association. Every listing prints the id, because without it a rename is indistinguishable from a new initiative.

delete removes the registry entry only. The record’s own references are reported and nothing cascades: no project, epic, milestone or issue is touched, and no association is silently repaired.

associate/dereference name exactly one of --project, --epic or --milestone; a well-formed reference that names nothing is stored and stays diagnosable (tix roadmap and tix lint report it), and a repeated association is an idempotent no-op.

Fields

command: InitiativeCommand

Roadmap

List and inspect the roadmap: initiatives ordered by target date

Read-only. Each row carries the target date (or the explicit undated state), the source-attributed summary — one contribution per referenced project/epic/milestone with its own value and shared policy version — and the ordered diagnostics, so a missing reference is visible on the row and an empty summary is explicit. No figure is blended across sources.

Fields

command: RoadmapCommand

Analytics

Read the burndown and scope analytics of a cycle or milestone, or write its deterministic chart document

Read-only. burndown prints the daily remaining/completed series the shared fold produces, projection the read-only end-date forecast at the caller’s --as-of, and export the versioned local chart document (WP04’s target, called by this verb rather than re-serialized). The period comes from the cycle/milestone’s own planning data and --from/--to replace the bound they name; count and estimate modes are explicit and an estimate without a compatible unit is refused rather than guessed. A value the record cannot support prints as - and never as a zero, a day with no recorded history is explicit about its coverage, and nothing here mutates an issue, a cycle or a snapshot. The remote gitlab/linear export namespaces are a different command (tix export) and are never consulted.

Fields

command: AnalyticsCommand

Export

Export local issues to an external tracker via glab/linear-cli, or write them into a beads workspace via bd

Fields

target: String

Target tracker: gitlab | linear | ics | beads

dry_run: bool

Print what would change without invoking the remote tracker

project: Option<String>

Override the configured project path (gitlab) or team (linear)

cycle: Option<String>

Cycle to export for ICS output

output: Option<String>

Output path for ICS export

verbose: bool

List the per-issue diagnostics — which local fields beads cannot hold

Off by default: a board of a few thousand issues produces hundreds of them, and a run that sends three issues should not rehearse the notes for the other thousand. The counts are always reported either way.

Import

Import open issues from an external tracker via glab/linear-cli, mirror a local GitHub Spec Kit project, or pull a beads workspace through bd

Fields

target: String

Target: gitlab | linear (remote trackers) | speckit (local mirror) | beads (a beads workspace, through bd)

triage_policy: Option<String>

Where an imported issue lands in the local triage inbox (WP07)

entry routes into [triage].entry_status and refuses a project with no [triage] section instead of quietly falling back; remote keeps the column the remote mapping named. Absent is the documented default: route when the project has an inbox, otherwise leave the mapping alone. Either way the report names the mapping that was used.

Rollover

Roll open issues forward from expired cycles to the next successor

Fields

cycle: Option<String>

Restrict rollover to one source cycle

yes: bool

Skip interactive confirmation

Search

Search issue files for a string (case-insensitive substring over full markdown)

Fields

string: String

Case-insensitive substring to match against the full markdown of every issue

with_archived: bool

Include archived issues in the search corpus

Render

Render the current board once and exit

Clean

Prune the centralized backups and remove the scattered ones

Backups live in .tix-backups/ beside the issues directory (#1581); --keep (default 10) bounds how many are kept per issue. A legacy *.tixbak or *.md.bak from an older release, still beside an issue, is removed too — by default each such file is confirmed interactively.

Fields

force: bool

Remove every legacy scattered backup without prompting

keep: usize

Backups to keep per issue in .tix-backups/

New

Open the TUI with the create-issue form already open

The session tix starts, with the modal that n opens already in front of you: one command to file an issue, instead of “start the board, then press n”. It is the interactive twin of tix create, which never opens the TUI.

Lint

Validate frontmatter option values in all issue files

Every finding renders as a rustc-style diagnostic on stderr: the file and line, the offending value, and a help: line naming the fix. An error sets the exit code (a broken file); a warning does not (a valid file that is worth a look) — so a store with warnings still exits 0.

What is checked:

• per issue: status against the board’s columns; priority, title, type, created/updated, estimate; the planning fields cycles, milestones, start_date, due_date; a ## History section that is not first in the body (fenced code examples are skipped) or an entry the grammar cannot read; and unrecognised top-level keys (a warning, since the key is preserved on write);
• the typed relationships: self-links, missing or conflicting targets, cycles, an unknown kind, and the retired links: key;
• the parent: hierarchy: self_parent, unresolved_parent, unknown_parent, cycle;
• related_issues entries: blank, or a local selector that resolves to nothing (paths and URLs are accepted verbatim);
• the configuration: board column/category mapping, [layout] drift, and a status: that contradicts the issue’s own recorded History.

Graph identity findings (ambiguous_target, duplicate_identity, missing_target, unresolved_parent) are repaired by pointing the reference at one canonical issue id. Run tix migrate issue-graph to preview conversion of legacy numeric endpoints.

Exit: 0 clean or warnings only, 1 any error, 2 usage or an internal failure.

Fields

no_foreign: bool

Do not lint the foreign repositories reachable from related_issues for this run (overrides lint_foreign_repositories in tix.toml).

Layout

Inspect or migrate the configured on-disk issue layout ([layout])

Fields

action: LayoutAction

Migrate

Migrate local issue data to the canonical issue graph

Fields

action: MigrateAction

Mcp

Serve the MCP protocol (JSON-RPC 2.0 over stdio) for agent tools

Template

Manage stable-ID issue/form templates

Templates live in [issue_templates.<id>] in tix.toml, keyed by an immutable stable ID with a mutable display name and an explicit scope. list/show are read-only; create/update/duplicate/delete persist through one atomic save, and a refused operation writes nothing.

Fields

action: TemplateAction

Trait Implementations

impl FromArgMatches for Command

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for Command

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand