CLI Reference¶

Need a quick command? Here's everything Quadro can do from the terminal.

How this fits together¶

You have three ways to work with tasks: use these CLI commands, edit the markdown files directly, or let your AI assistant manage them through MCP. All three work with the same files in your tasks/ directory.

This page covers the CLI commands. Use them when you want quick, direct control.

Quick tip: Running quadro without any command defaults to quadro list.

Commands¶

add ¶

add(
    title: str,
    description: str | None,
    milestone: str | None,
) -> None

Create a new task with the specified title.

Creates a new task in TODO status and saves it as a markdown file. Tasks can optionally be assigned to a milestone for organization and include a description for additional context.

Examples:

$ quadro add "Implement login feature"
$ quadro add "Add user authentication" --milestone mvp
$ quadro add "Fix bug in parser" --description "Parser fails on edge case"
$ quadro add "Add tests" -d "Write unit tests for auth module" --milestone mvp

list_tasks ¶

list_tasks(
    milestone: str | None,
    todo: bool,
    progress: bool,
    done: bool,
) -> None

List all tasks with their status and details.

Displays a formatted table of tasks showing ID, status, title, and milestone. Tasks can be filtered by milestone and status.

Status filters can be combined to show multiple statuses. If no status filters are provided, all tasks are shown.

This is the default command when running 'quadro' without arguments.

Examples:

$ quadro list
$ quadro list --milestone mvp
$ quadro list --todo
$ quadro list --todo --progress
$ quadro list --done --milestone mvp

start ¶

start(task_id: int) -> None

Mark a task as in progress.

Changes the status of a task from TODO to PROGRESS, indicating that work has begun on the task.

If the task is already in progress or completed, a warning is displayed but the command exits successfully.

Examples:

$ quadro start 1

done ¶

done(task_id: int) -> None

Mark a task as completed.

Changes the status of a task to DONE and records the completion timestamp. This indicates that work on the task has been successfully finished.

If the task is already completed, a warning is displayed but the command exits successfully.

Examples:

$ quadro done 1

show ¶

show(task_id: int) -> None

Display detailed information about a specific task.

Shows the complete details of a task including its ID, title, status, description, milestone, creation date, and completion date (if applicable).

The task details are rendered in a formatted, color-coded display.

Examples:

$ quadro show 1

milestones ¶

milestones() -> None

Display a summary of all milestones and their tasks.

Shows a grouped view of tasks organized by milestone, with counts of tasks in each status (TODO, PROGRESS, DONE) per milestone. Useful for tracking progress across different project phases or releases.

Only tasks that have been assigned to a milestone are included in this view. Tasks without a milestone are not shown.

Examples:

$ quadro milestones

move ¶

move(task_id: int, to: str) -> None

Move a task to a different milestone.

Relocates a task's file from one milestone directory to another, or between the root directory and a milestone. The task's milestone field is updated accordingly.

Use 'root' as the target to move a task out of any milestone to the root directory.

Examples:

$ quadro move 1 --to mvp
$ quadro move 5 --to root
$ quadro move 3 --to v2.0

edit ¶

edit(task_id: int) -> None

Edit a task's details in your default text editor.

Opens the task's markdown file in the system's default editor (determined by the EDITOR environment variable). You can modify the title, description, status, and milestone. Changes are validated and saved upon editor exit.

The task file is opened in markdown format with frontmatter containing metadata (status, milestone, created date) and the task body containing the title and description. If you exit the editor without saving or if no changes are made, the task remains unmodified.

Invalid modifications (e.g., invalid status values) will be rejected with an error message.

Examples:

$ quadro edit 1

delete ¶

delete(task_id: int, yes: bool) -> None

Delete a task permanently.

Removes a task and its associated file from the filesystem. By default, displays the task details and prompts for confirmation before deletion to prevent accidental data loss.

WARNING: This operation is irreversible. Once deleted, the task file is permanently removed from the filesystem and cannot be recovered.

The confirmation prompt shows the full task details before deletion, allowing you to verify you're deleting the correct task. The confirmation defaults to 'No' for safety.

Examples:

$ quadro delete 1
$ quadro delete 1 --yes
$ quadro delete 1 -y

Environment Variables¶

The edit command uses your EDITOR environment variable. Set it in your shell profile:

export EDITOR=vim
# or
export EDITOR="code --wait"

If you don't set EDITOR, Quadro will try common editors like vim, nano, or vi.

Exit Codes¶

Commands return standard exit codes:

0 means success
1 means something went wrong (task not found, file error, etc.)

Useful if you're using Quadro in scripts.

Getting Help¶

Every command shows help with the --help flag:

quadro --help
quadro add --help
quadro list --help