steve/pcli
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 4 Wiki Activity
Files
main
pcli/openspec/changes/archive/2026-02-09-planka-cli-v1/specs/cli-commands/spec.md
T
Steve Cliff b07572fed5 Released v1
2026-02-12 10:37:19 +00:00

11 KiB
Raw Permalink Blame History

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), --token (string, overrides PLANKA_TOKEN), 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 token 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

Requirement: Project commands

The system SHALL provide a project command group with subcommands list and get. 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.

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

Requirement: Board commands

The system SHALL provide a board command group with subcommands get and actions. 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.

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

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: 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
Reference in New Issue View Git Blame Copy Permalink