---
description: This document outlines how to use the `agent-checklist` CLI tool to manage a list of tasks. This tool is designed to help an AI agent keep track of its objectives and progress.
globs: 
alwaysApply: false
---
# Using the Agent Checklist CLI

This document outlines how to use the `agent-checklist` CLI tool to manage multiple checklists and their tasks.

The main script for the CLI tool is `[index.ts](mdc:index.ts)`. The project's dependencies and scripts can be found in `[package.json](mdc:package.json)`.

## Core Concepts

*   **Checklist**: A named container for tasks. Each checklist has a unique ID and name.
*   **Item/Task**: An individual action item within a checklist. Each task has a unique ID, a description, and a completion status.

## Running Commands

You can run the CLI tool using Bun:

```bash
bun run index.ts <command> [arguments]
```

If the package has been linked (e.g., via `bun link`), you can also use its global name:

```bash
agent-checklist <command> [arguments]
```

Tasks are stored locally in a `checklist.sqlite` file.

## Available Commands

### 1. Create a new checklist

*   **Command**: `agent-checklist create <name> [-a|--add <tasks...>]`
*   **Description**: Creates a new checklist.
*   **Arguments**:
    *   `<name>` (required): The name for the new checklist (e.g., "Project Setup", "Daily Chores").
*   **Options**:
    *   `-a, --add <tasks...>` (optional): A list of initial tasks to add to the newly created checklist. Enclose each task in quotes if it contains spaces.
*   **Example (create an empty checklist)**:
    ```bash
    agent-checklist create "Grocery List"
    ```
    (Assumes this creates checklist with ID 1, for example)
*   **Example (create a checklist with initial tasks)**:
    ```bash
    agent-checklist create "Road Trip Prep" -a "Check tire pressure" "Pack snacks" "Download offline maps"
    ```
    (Assumes this creates checklist with ID 2, for example. Tasks will be added to checklist 2)

### 2. List checklists or tasks

*   **Command**: `agent-checklist list [checklistId]`
*   **Description**: Lists all available checklists or, if a `checklistId` is provided, lists all tasks within that specific checklist.
*   **Arguments**:
    *   `[checklistId]` (optional): The ID of the checklist whose tasks you want to view.
*   **Example (list all checklists)**:
    ```bash
    agent-checklist list
    ```
    Output might look like:
    ```
    Available checklists:
    1: Grocery List
    2: Road Trip Prep
    ```
*   **Example (list tasks for a specific checklist)**:
    ```bash
    agent-checklist list 2
    ```
    Output might look like:
    ```
    Tasks for checklist "Road Trip Prep" (ID: 2):
    [ ] 4: Check tire pressure
    [ ] 5: Pack snacks
    [ ] 6: Download offline maps
    ```

### 3. Add a task to a checklist

*   **Command**: `agent-checklist add <checklistId> <task>`
*   **Description**: Adds a new task to an existing checklist.
*   **Arguments**:
    *   `<checklistId>` (required): The ID of the checklist to add the task to.
    *   `<task>` (required): The description of the task. Enclose in quotes if it contains spaces.
*   **Example**:
    ```bash
    agent-checklist add 1 "Buy milk"
    agent-checklist add 1 "Get eggs"
    ```

### 4. Mark a task as completed

*   **Command**: `agent-checklist complete <itemId>`
*   **Description**: Marks a specific task as completed.
*   **Arguments**:
    *   `<itemId>` (required): The ID of the task to mark as complete. You can get this ID from the `list` command.
*   **Example**:
    ```bash
    agent-checklist complete 5 
    ```
    (Assuming item ID 5 was "Pack snacks" from the "Road Trip Prep" list)
    Running `agent-checklist list 2` again would show:
    ```
    Tasks for checklist "Road Trip Prep" (ID: 2):
    [ ] 4: Check tire pressure
    [x] 5: Pack snacks
    [ ] 6: Download offline maps
    ```

### 5. Remove a task

*   **Command**: `agent-checklist remove <itemId>`
*   **Description**: Removes a specific task from its checklist.
*   **Arguments**:
    *   `<itemId>` (required): The ID of the task to remove.
*   **Example**:
    ```bash
    agent-checklist remove 4
    ```

### 6. Remove a checklist

*   **Command**: `agent-checklist remove-checklist <checklistId>`
*   **Alias**: `agent-checklist rmc <checklistId>`
*   **Description**: Removes an entire checklist and all of its associated tasks.
*   **Arguments**:
    *   `<checklistId>` (required): The ID of the checklist to remove.
*   **Example**:
    ```bash
    agent-checklist remove-checklist 2
    ```

### 7. Initialize CLI Rule for Cursor

*   **Command**: `agent-checklist init [-p|--platform <platform>]`
*   **Description**: Installs a rule file (`agent_checklist_cli_usage.mdc`) into the `.cursor/rules/` directory of the current project. This helps Cursor understand how to use this CLI.
*   **Options**:
    *   `-p, --platform <platform>` (optional): The platform for which to install the rule. Defaults to `cursor`.
*   **Example**:
    ```bash
    agent-checklist init
    ```
    This will copy the rule file to `.cursor/rules/agent_checklist_cli_usage.mdc` in your current project.

## Workflow Example

1.  **Create a new project checklist**: `agent-checklist create "My New Website" -a "Design homepage" "Setup backend API" "Deploy to server"`
    *   Let's say this creates checklist ID 3.
2.  **List tasks for the new checklist**: `agent-checklist list 3`
3.  **Add another task**: `agent-checklist add 3 "Write user documentation"`
4.  **Mark a task as done**: `agent-checklist complete <itemId_for_Design_Homepage>` (get the ID from the `list` command)
5.  **List all checklists**: `agent-checklist list`
6.  **Remove a task**: `agent-checklist remove <itemId_for_Setup_Backend_API>`
7.  **Remove the entire checklist when done**: `agent-checklist remove-checklist 3`

By using these commands, an AI agent can effectively manage its to-do list directly from the command line.