cli

class shai_tix.cli.Cli(dir_root: Path | None = None)

CLI for shai_tix task management system (designed for AI agents).

If running multiple CLI commands in sequence, call rebuild_index_db first to sync the SQLite index with the filesystem once, avoiding redundant rebuilds on each query command.

Example:

shai-tix rebuild_index_db
shai-tix list_stories
shai-tix list_tasks
shai-tix search_stories --title "auth"

rebuild_index_db(root: str | None = None)

Rebuild the SQLite index from filesystem.

Call this before running multiple query commands to avoid repeated rebuilds.

Parameters:

root – Project root directory (default: current directory).

list_stories(limit: int = 20, root: str | None = None)

List all stories, ordered by ID descending (newest first).

Output format: [{id}] {date} - {title}

Parameters:

• limit – Maximum number of stories to display.

• root – Project root directory (default: current directory).

search_stories(title: str = None, date_lower: str = None, date_upper: str = None, id_lower: int = None, id_upper: int = None, status: str = None, limit: int = 20, root: str | None = None)

Search stories by title, date range, ID range, or status.

Results are ordered by ID descending (newest first). Output format: [{id}] {date} - {title}

Parameters:

• title – Search keywords. The title is split into tokens by spaces, and a story matches if ANY token is found in its title (case-insensitive). Example: --title "login auth" matches stories containing “login” OR “auth”.

• date_lower – Minimum date (YYYY-MM-DD).

• date_upper – Maximum date (YYYY-MM-DD).

• id_lower – Minimum story ID.

• id_upper – Maximum story ID.

• status – Comma-separated status values to filter by. A story matches if its status is ANY of the specified values. Example: --status "TODO,IN_PROGRESS" matches TODO or IN_PROGRESS stories. Valid values: TODO, IN_PROGRESS, COMPLETED, BLOCKED, CANCELED.

• limit – Maximum number of stories to display.

• root – Project root directory (default: current directory).

create_story(title: str, description: str = None, root: str | None = None)

Create a new story.

Parameters:

• title – Story title. Only letters (a-z, A-Z), digits (0-9), and spaces are allowed. Special characters will cause an error.

• description – Story description (markdown content).

• root – Project root directory (default: current directory).

get_story(id: int, root: str | None = None)

Get a story by ID with full details.

Output format:

[{id}] {date} - {title}
Status: {status}
Path: {path}

--- Description ---
{description content or "(No description)"}

--- Report ---
{report content or "(No report)"}

Parameters:

• id – Story ID.

• root – Project root directory (default: current directory).

update_story(id: int, title: str = None, status: str = None, description: str = None, report: str = None, root: str | None = None)

Update a story by ID.

Parameters:

• id – Story ID.

• title – New title. Only letters (a-z, A-Z), digits (0-9), and spaces are allowed. Changing title will rename the story folder.

• status – New status (TODO, IN_PROGRESS, COMPLETED, BLOCKED, CANCELED).

• description – New description (markdown content).

• report – New report (markdown content).

• root – Project root directory (default: current directory).

delete_story(id: int, root: str | None = None)

Delete a story by ID.

Parameters:

• id – Story ID.

• root – Project root directory (default: current directory).

list_tasks(limit: int = 20, root: str | None = None)

List all tasks, ordered by ID descending (newest first).

Output format: [{id}] {date} - {title} (story: {story_id})

Parameters:

• limit – Maximum number of tasks to display.

• root – Project root directory (default: current directory).

list_tasks_by_story(story_id: int, limit: int = 20, root: str | None = None)

List all tasks under a story, ordered by ID descending (newest first).

Output format: [{id}] {date} - {title}

Parameters:

• story_id – Parent story ID.

• limit – Maximum number of tasks to display.

• root – Project root directory (default: current directory).

search_tasks(title: str = None, date_lower: str = None, date_upper: str = None, id_lower: int = None, id_upper: int = None, status: str = None, limit: int = 20, root: str | None = None)

Search tasks by title, date range, ID range, or status.

Results are ordered by ID descending (newest first). Output format: [{id}] {date} - {title} (story: {story_id})

Parameters:

• title – Search keywords. The title is split into tokens by spaces, and a task matches if ANY token is found in its title (case-insensitive). Example: --title "login form" matches tasks containing “login” OR “form”.

• date_lower – Minimum date (YYYY-MM-DD).

• date_upper – Maximum date (YYYY-MM-DD).

• id_lower – Minimum task ID.

• id_upper – Maximum task ID.

• status – Comma-separated status values to filter by. A task matches if its status is ANY of the specified values. Example: --status "TODO,IN_PROGRESS" matches TODO or IN_PROGRESS tasks. Valid values: TODO, IN_PROGRESS, COMPLETED, BLOCKED, CANCELED.

• limit – Maximum number of tasks to display.

• root – Project root directory (default: current directory).

create_task(story_id: int, title: str, description: str = None, root: str | None = None)

Create a new task under a story.

Parameters:

• story_id – Parent story ID.

• title – Task title. Only letters (a-z, A-Z), digits (0-9), and spaces are allowed. Special characters will cause an error.

• description – Task description (markdown content).

• root – Project root directory (default: current directory).

get_task(id: int, root: str | None = None)

Get a task by ID with full details.

Output format:

[{id}] {date} - {title}
Status: {status}
Story ID: {story_id}
Path: {path}

--- Description ---
{description content or "(No description)"}

--- Report ---
{report content or "(No report)"}

Parameters:

• id – Task ID.

• root – Project root directory (default: current directory).

update_task(id: int, title: str = None, status: str = None, description: str = None, report: str = None, root: str | None = None)

Update a task by ID.

Parameters:

• id – Task ID.

• title – New title. Only letters (a-z, A-Z), digits (0-9), and spaces are allowed. Changing title will rename the task folder.

• status – New status (TODO, IN_PROGRESS, COMPLETED, BLOCKED, CANCELED).

• description – New description (markdown content).

• report – New report (markdown content).

• root – Project root directory (default: current directory).

delete_task(id: int, root: str | None = None)

Delete a task by ID.

Parameters:

• id – Task ID.

• root – Project root directory (default: current directory).