pcli/openspec/specs/cli-commands/spec.md

ADDED Requirements

Requirement: Root command and global flags

The system SHALL provide a root command pcli that serves as the entry point. The root command SHALL register global flags: --format (string, default json, values json or table), --url (string, overrides PLANKA_URL), --api-key (string, overrides PLANKA_API_KEY), and --log-level (string, default warn, values debug, info, warn, error). The root command SHALL initialize the logger based on --log-level and configure it to write structured JSON to stderr. The root command SHALL validate that URL and API key are available (from flags or environment) before executing any subcommand.

Scenario: Display help

• WHEN pcli is run with no arguments or --help
• THEN the system SHALL display usage information listing all resource subcommands and global flags

Scenario: Invalid format flag

• WHEN --format is set to an unsupported value
• THEN the system SHALL print an error and exit with code 1

Scenario: Log level controls output

• WHEN --log-level=debug is set
• THEN DEBUG-level log entries SHALL appear on stderr
• AND stdout SHALL contain only the command's data output

Scenario: Missing API key

• WHEN neither PLANKA_API_KEY environment variable nor --api-key flag is provided
• THEN the system SHALL print an error indicating PLANKA_API_KEY must be set via --api-key flag or PLANKA_API_KEY environment variable
• AND the system SHALL exit with code 1

Requirement: Project commands

The system SHALL provide a project command group with subcommands list, get, create, and delete. pcli project list SHALL call the client's ListProjects method and output the result. pcli project get <id> SHALL accept a project ID as a positional argument, call GetProject, and output the result. pcli project create SHALL create a new project. pcli project delete <id> SHALL delete a project.

Scenario: List projects

• WHEN pcli project list is executed
• THEN the system SHALL output all accessible projects

Scenario: Get project by ID

• WHEN pcli project get <id> is executed with a valid project ID
• THEN the system SHALL output the project details

Scenario: Get project missing ID

• WHEN pcli project get is executed without an ID argument
• THEN the system SHALL print an error indicating the ID is required and exit with code 1

Scenario: Create project

• WHEN pcli project create --name "My Project" --type private --description "A test project" is executed
• THEN the system SHALL create the project and output the created project

Scenario: Create project missing required flags

• WHEN pcli project create is executed without --name or --type
• THEN the system SHALL print an error indicating the required flags and exit with code 1

Scenario: Create project with insufficient permissions

• WHEN pcli project create is executed with invalid API credentials
• THEN the system SHALL output "create project: authentication failed — check your API key"

Scenario: Delete project

• WHEN pcli project delete <id> is executed with a valid project ID
• THEN the system SHALL delete the project and output a success confirmation

Scenario: Delete project with insufficient permissions

• WHEN pcli project delete <id> is executed by a user without project manager permissions
• THEN the system SHALL output "delete project: permission denied (requires project manager role)"

Scenario: Delete project not found

• WHEN pcli project delete <id> is executed with a non-existent project ID
• THEN the system SHALL output "delete project: not found — the resource may not exist or you may not have access to it"

Requirement: Board list command

The system SHALL provide a board list subcommand. pcli board list SHALL call the client's ListBoards method and output all accessible boards. The command SHALL accept an optional --project <name> flag (string). When --project is provided, the system SHALL filter boards to only those belonging to the specified project (see board-list-filtering spec for filtering behavior).

Scenario: List all boards

• WHEN pcli board list is executed without flags
• THEN the system SHALL output all accessible boards

Scenario: List boards filtered by project

• WHEN pcli board list --project "project1" is executed
• THEN the system SHALL output only boards belonging to the specified project

Requirement: Board commands

The system SHALL provide a board command group with subcommands list, get, actions, create, and delete. pcli board list SHALL list all accessible boards and accept an optional --project <name> flag for filtering. pcli board get <id> SHALL accept a board ID as a positional argument and output the board details. pcli board actions <id> SHALL accept a board ID and an optional --limit flag (int, default 0) and output the board's action history. pcli board create SHALL create a new board. pcli board delete <id> SHALL delete a board.

Scenario: Get board

• WHEN pcli board get <id> is executed
• THEN the system SHALL output the board details including its lists

Scenario: List board actions

• WHEN pcli board actions <id> is executed
• THEN the system SHALL output the board's action history

Scenario: List board actions with limit

• WHEN pcli board actions <id> --limit 10 is executed
• THEN the system SHALL output at most 10 action entries

Scenario: Create board

• WHEN pcli board create --project <id> --name "Development Board" --position 65536 is executed
• THEN the system SHALL create the board and output the created board

Scenario: Create board missing required flags

• WHEN pcli board create is executed without --project or --name
• THEN the system SHALL print an error indicating the required flags and exit with code 1

Scenario: Create board with insufficient permissions

• WHEN pcli board create --project <id> --name "Board" is executed by a user without project manager permissions on the project
• THEN the system SHALL output "create board: permission denied (requires project manager role)"

Scenario: Create board project not found

• WHEN pcli board create --project <id> --name "Board" is executed with a project the user cannot access
• THEN the system SHALL output "create board: not found — the resource may not exist or you may not have access to it"

Scenario: Delete board

• WHEN pcli board delete <id> is executed with a valid board ID
• THEN the system SHALL delete the board and output a success confirmation

Scenario: Delete board with insufficient permissions

• WHEN pcli board delete <id> is executed by a user without project manager permissions
• THEN the system SHALL output "delete board: permission denied (requires project manager role)"

Scenario: Delete board not found

• WHEN pcli board delete <id> is executed with a non-existent board ID
• THEN the system SHALL output "delete board: not found — the resource may not exist or you may not have access to it"

Requirement: Card commands

The system SHALL provide a card command group with subcommands: list, get, create, update, delete, duplicate, move, assign, unassign, add-label, remove-label, actions.

pcli card list SHALL require either --board <id> or --list <id> flag and accept an optional --limit flag. pcli card get <id> SHALL accept a card ID as a positional argument. pcli card create SHALL require --list <id> and --name <name> flags and accept optional flags: --description, --type, --position, --due-date, --due-completed. pcli card update <id> SHALL accept a card ID and optional flags for each updatable field: --name, --description, --type, --position, --due-date, --due-completed. pcli card delete <id> SHALL accept a card ID. pcli card duplicate <id> SHALL accept a card ID and optional --name and --position flags. pcli card move <id> SHALL require --list <id> and accept optional --position flag. pcli card assign <id> SHALL require --user <userId>. pcli card unassign <id> SHALL require --user <userId>. pcli card add-label <id> SHALL require --label <labelId>. pcli card remove-label <id> SHALL require --label <labelId>. pcli card actions <id> SHALL accept an optional --limit flag.

Scenario: List cards by board

• WHEN pcli card list --board <id> is executed
• THEN the system SHALL output all cards across all lists in the board, each enriched with listName

Scenario: List cards by list

• WHEN pcli card list --list <id> is executed
• THEN the system SHALL output cards in the specified list

Scenario: List cards with limit

• WHEN pcli card list --list <id> --limit 5 is executed
• THEN the system SHALL output at most 5 cards

Scenario: Card list missing board or list flag

• WHEN pcli card list is executed without --board or --list
• THEN the system SHALL print an error indicating one is required and exit with code 1

Scenario: Get card

• WHEN pcli card get <id> is executed
• THEN the system SHALL output the card details

Scenario: Create card

• WHEN pcli card create --list <id> --name "Task name" is executed
• THEN the system SHALL create the card and output the created card

Scenario: Create card missing required flags

• WHEN pcli card create is executed without --list or --name
• THEN the system SHALL print an error and exit with code 1

Scenario: Update card

• WHEN pcli card update <id> --name "New name" is executed
• THEN the system SHALL update the card and output the updated card

Scenario: Delete card

• WHEN pcli card delete <id> is executed
• THEN the system SHALL delete the card and output a success confirmation

Scenario: Duplicate card

• WHEN pcli card duplicate <id> is executed
• THEN the system SHALL duplicate the card and output the new card

Scenario: Move card

• WHEN pcli card move <id> --list <listId> is executed
• THEN the system SHALL update the card's listId (and optionally position) and output the updated card

Scenario: Assign user to card

• WHEN pcli card assign <id> --user <userId> is executed
• THEN the system SHALL add the user as a card member

Scenario: Unassign user from card

• WHEN pcli card unassign <id> --user <userId> is executed
• THEN the system SHALL remove the user from the card's members

Scenario: Add label to card

• WHEN pcli card add-label <id> --label <labelId> is executed
• THEN the system SHALL add the label to the card

Scenario: Remove label from card

• WHEN pcli card remove-label <id> --label <labelId> is executed
• THEN the system SHALL remove the label from the card

Scenario: List card actions

• WHEN pcli card actions <id> is executed
• THEN the system SHALL output the card's action history

Requirement: Comment commands

The system SHALL provide a comment command group with subcommands: list, create, update, delete. pcli comment list SHALL require --card <id> and accept optional --limit. pcli comment create SHALL require --card <id> and --text <text>. pcli comment update <id> SHALL require --text <text>. pcli comment delete <id> SHALL accept a comment ID.

Scenario: List comments

• WHEN pcli comment list --card <id> is executed
• THEN the system SHALL output comments for the card

Scenario: Create comment

• WHEN pcli comment create --card <id> --text "comment text" is executed
• THEN the system SHALL create the comment and output the created comment

Scenario: Update comment

• WHEN pcli comment update <id> --text "updated text" is executed
• THEN the system SHALL update the comment and output the updated comment

Scenario: Delete comment

• WHEN pcli comment delete <id> is executed
• THEN the system SHALL delete the comment and output a success confirmation

Requirement: Task list commands

The system SHALL provide a task-list command group with subcommands: create, get, update, delete. pcli task-list create SHALL require --card <id> and --name <name> and accept optional flags: --position, --show-on-front, --hide-completed. pcli task-list get <id> SHALL accept a task list ID. pcli task-list update <id> SHALL accept optional flags for each updatable field. pcli task-list delete <id> SHALL accept a task list ID.

Scenario: Create task list

• WHEN pcli task-list create --card <id> --name "Checklist" is executed
• THEN the system SHALL create the task list and output the created task list

Scenario: Get task list

• WHEN pcli task-list get <id> is executed
• THEN the system SHALL output the task list details including its tasks

Scenario: Update task list

• WHEN pcli task-list update <id> --name "Renamed" is executed
• THEN the system SHALL update the task list and output the updated task list

Scenario: Delete task list

• WHEN pcli task-list delete <id> is executed
• THEN the system SHALL delete the task list and output a success confirmation

Requirement: Task commands

The system SHALL provide a task command group with subcommands: create, update, delete. pcli task create SHALL require --task-list <id> and --name <name> and accept optional flags: --position, --completed, --assignee, --linked-card. pcli task update <id> SHALL accept optional flags for each updatable field: --name, --position, --completed, --assignee, --task-list. pcli task delete <id> SHALL accept a task ID.

Scenario: Create task

• WHEN pcli task create --task-list <id> --name "Do something" is executed
• THEN the system SHALL create the task and output the created task

Scenario: Update task

• WHEN pcli task update <id> --completed is executed
• THEN the system SHALL mark the task as completed and output the updated task

Scenario: Move task to different list

• WHEN pcli task update <id> --task-list <newListId> is executed
• THEN the system SHALL move the task to the specified task list

Scenario: Delete task

• WHEN pcli task delete <id> is executed
• THEN the system SHALL delete the task and output a success confirmation

Requirement: Status command

The system SHALL provide a top-level status command registered directly on the root command (not as a subcommand of any resource group). pcli status SHALL take no positional arguments. The command SHALL accept an optional --project <name> flag (string) to filter boards by project name. The command SHALL fetch all boards via ListBoards, optionally filter by project, then fetch each board's details via GetBoard sequentially, aggregate card counts per list, and output the result via the standard output.Print mechanism respecting the global --format flag.

Scenario: Run status command

• WHEN pcli status is executed
• THEN the system SHALL output a summary of all boards with their lists and card counts

Scenario: Run status command with project filter

• WHEN pcli status --project "MyProject" is executed
• THEN the system SHALL output a summary of only boards belonging to "MyProject"

Scenario: Status command respects format flag

• WHEN pcli status --format table is executed
• THEN the output SHALL be in table format

Scenario: Status command default format

• WHEN pcli status is executed without a --format flag
• THEN the output SHALL be in JSON envelope format

Requirement: Label commands

The system SHALL provide a label command group with subcommands: create, update, delete. pcli label create SHALL require --board <id> and --name <name> and accept optional flags: --color, --position. pcli label update <id> SHALL accept optional flags: --name, --color, --position. pcli label delete <id> SHALL accept a label ID.

Scenario: Create label

• WHEN pcli label create --board <id> --name "Bug" --color red is executed
• THEN the system SHALL create the label and output the created label

Scenario: Update label

• WHEN pcli label update <id> --name "Feature" --color green is executed
• THEN the system SHALL update the label and output the updated label

Scenario: Delete label

• WHEN pcli label delete <id> is executed
• THEN the system SHALL delete the label and output a success confirmation