BlocPad CLI (blocpad)

BlocPad CLI is a terminal interface for reading and mutating BlocPad context (projects, tasks, pages, goals, epics, stories, sprints) and driving safe, step-by-step workflows for engineering agents.

Supports both Task Management and Traditional PM project modes.

Install

npm i -g blocpad-cli
blocpad --help

Or run without installing:

npx blocpad-cli --help

Login (one-time)

Default API base URL is https://www.blocpad.com.

1. Create a Personal Access Token in BlocPad:

• Go to https://www.blocpad.com/settings
• Create a token (you'll get a bp_pat_... value). Recommended scopes: cli:read, cli:write, cli:tokens

2. Log in:

blocpad auth login --token bp_pat_...

3. Verify:

blocpad auth status
blocpad context show        # shows project, task, and PM mode

Commands overview

Authentication & setup

blocpad auth login           # log in with a PAT
blocpad auth logout          # remove stored credentials
blocpad auth status          # show current auth state and user info
blocpad auth token create    # create a new personal access token

Context (active project & task)

blocpad context show         # display active project, task, and PM mode
blocpad context set-project <projectId>
blocpad context set-task <taskId|taskNumber>
blocpad context clear-task   # unset the active task (keep project)
blocpad context select       # interactive picker for project and task
blocpad context export --md  # export full context (task + comments + pages + linked tasks)

Projects

blocpad projects list --json   # includes pm_mode and estimation_mode
blocpad projects show <id>

Tasks (works in both TM and PM modes)

blocpad task ERS-1 --md                # quick context export (includes pages + linked tasks)
blocpad tasks list --md                # list all tasks
blocpad tasks list --hide-subtasks     # top-level only
blocpad tasks show ERS-1 --md          # show a single task with full details
blocpad tasks create --title "..." --description "..."
blocpad tasks comments ERS-1 --md      # list comments on a task
blocpad tasks breadcrumb ERS-1         # parent chain from root to task
blocpad tasks tree ERS-1 --md          # subtask tree rooted at a task
blocpad tasks next ERS-1 --json        # pick the next leaf subtask to work on
blocpad tasks focus ERS-1 --md         # export full context for the next leaf (AI workflow)

Pages / Wiki

blocpad pages list --json
blocpad pages show <pageId> --md

Traditional PM (requires pm_mode='traditional')

# Full hierarchy view: Goals > Epics > Stories > Tasks + Sprints
blocpad pm tree --json
blocpad pm tree --max-depth 2          # goals + epics only

# Goals
blocpad goals list                     # list all goals
blocpad goals show <goalId> --md       # goal with child epics + linked pages

# Epics
blocpad epics list                     # list all epics
blocpad epics list --goal <goalId>     # filter by goal
blocpad epics show <epicId> --md       # epic with child stories + linked pages

# Stories
blocpad stories list                   # list all stories
blocpad stories list --epic <epicId>   # filter by epic
blocpad stories list --sprint <sprintId>  # filter by sprint
blocpad stories show <storyId> --md    # story with child tasks + sprint info + pages

# Sprints
blocpad sprints list                   # list all sprints with story/task counts
blocpad sprints show <sprintId> --md   # sprint with its stories and tasks

Proposals (propose-review-apply workflow)

All mutations go through a safe propose → review → apply pipeline. Changes are stored locally until you explicitly apply them.

Task mutations

blocpad propose task status --status done --task-number 42
blocpad propose task summary --summary "Updated desc" --task-number 42
blocpad propose task comment --body "Fixed the bug" --task-number 42
blocpad propose task create --title "Add login" --parent 42
blocpad propose task child create --title "Write tests" --task-number 42
blocpad propose task checklist add --item "Unit tests" --task-number 42
blocpad propose task checklist replace --items "Step 1,Step 2" --task-number 42
blocpad propose task meta --set priority=high --task-number 42
blocpad propose task parent set --parent 10 --task-number 42
blocpad propose task parent clear --task-number 42
blocpad propose task children reorder --order id1,id2,id3 --task-number 42
blocpad propose task delete --mode orphan --task-number 42

PM mutations (Traditional PM mode)

# Goals
blocpad propose goal create --title "Improve UX" --description "Focus on dashboard"
blocpad propose goal update --goal <goalId> --title "New title"
blocpad propose goal delete --goal <goalId>

# Epics
blocpad propose epic create --title "Dashboard redesign" --goal <goalId> --start 2026-03-01 --end 2026-06-01
blocpad propose epic update --epic <epicId> --title "Updated"
blocpad propose epic delete --epic <epicId>

# Stories
blocpad propose story create --title "Add widgets" --epic <epicId> --status backlog
blocpad propose story status --story <storyId> --status in_progress
blocpad propose story update --story <storyId> --title "Updated" --description "New desc"
blocpad propose story delete --story <storyId>

# Sprints
blocpad propose sprint create --name "Sprint 5" --start 2026-03-01 --end 2026-03-14
blocpad propose sprint start --sprint <sprintId>
blocpad propose sprint close --sprint <sprintId>
blocpad propose sprint update --sprint <sprintId> --name "Sprint 5.1"
blocpad propose sprint add-story --sprint <sprintId> --story <storyId>
blocpad propose sprint remove-story --sprint <sprintId> --story <storyId>
blocpad propose sprint add-task --sprint <sprintId> --task-number 42
blocpad propose sprint remove-task --sprint <sprintId> --task-number 42

Review and apply

blocpad proposals list                 # list all pending proposals
blocpad proposals show <proposalId>    # show details of a specific proposal
blocpad proposals discard <proposalId> # discard a single proposal
blocpad proposals discard --all        # clear all pending proposals
blocpad apply --dry-run                # preview without executing
blocpad apply                          # apply with interactive confirmation
blocpad apply --yes                    # apply without confirmation (for CI/AI tools)

Global options

| Flag | Description | |---|---| | --json | Machine-readable JSON output | | --md | Markdown output (where supported) | | --base-url <url> | Override BlocPad API base URL | | --token <token> | Override auth token (discouraged; prefer auth login) | | --project <id> | Override active project for this command | | --task <id> | Override active task for this command | | --task-number <n> | Select task by task_number instead of ID | | --version, -v | Print CLI version | | --help, -h | Show help for any command |

Cursor Prompt (Frontend Agent)

Paste this into Cursor's rules / custom instructions:

You are a frontend engineering agent working from BlocPad tasks via the `blocpad` CLI.
Your job is to fetch tasks, detect parent/child nesting, and implement independent leaf tasks first
(leaf = no incomplete subtasks).

Commands you may use:
- List tasks (includes hierarchy fields): `blocpad tasks list --json`
- Show task detail: `blocpad tasks show <TASK_NUMBER_OR_ID> --md`
- Get breadcrumb/tree view: `blocpad tasks tree <TASK_NUMBER_OR_ID> --json`
- Pick next leaf under a parent: `blocpad tasks next <TASK_NUMBER_OR_ID> --json`
- Export full context for next leaf: `blocpad tasks focus <TASK_NUMBER_OR_ID> --md`
- PM hierarchy (if traditional mode): `blocpad pm tree --json`
- Update task status: `blocpad propose task status --status done --task-number <N>` then `blocpad apply --yes`

Workflow:
1) Fetch all tasks:
   - Run `blocpad tasks list --json`
2) Build a hierarchy in memory using `parentTaskId` / `parent_task_id`:
   - Identify roots (no parent) and children.
   - Identify leaf tasks (no children).
3) Prioritize work:
   - Work on independent leaves first: leaf tasks whose parent is null OR whose parent is already done OR tasks that don't depend on unfinished siblings.
   - Prefer status order: `in_progress` first, then `todo/open`, skip `done`.
4) For each chosen leaf task:
   - Load full context: `blocpad tasks show <LEAF_TASK_NUMBER_OR_ID> --md`
   - Implement only that task in the codebase (frontend scope).
   - Run relevant frontend checks/tests/build.
5) After finishing one leaf task:
   - Mark it done: `blocpad propose task status --status done --task-number <N>` then `blocpad apply --yes`
   - Repeat step 1–4 until no remaining leaf tasks exist.
6) If a task is a parent (has children), do not implement it directly—use:
   - `blocpad tasks next <PARENT_TASK_NUMBER_OR_ID> --json`
   - `blocpad tasks focus <PARENT_TASK_NUMBER_OR_ID> --md`
   and work on the suggested leaf.

Rules:
- Never work on more than one task at a time.
- If a task is unclear or blocked by missing backend/API/design, ask one focused question and stop.
- Keep changes minimal, production-quality, and aligned with existing UI patterns.

Docs

• Full documentation
• docs/CLI.md
• docs/BACKEND_CHECKLIST.md

Publishing to npm (maintainers)

npm login
npm test
npm run typecheck
npm run build
npm_config_cache="$PWD/.npm-cache" npm pack --dry-run
npm_config_cache="$PWD/.npm-cache" npm publish --access public
rm -rf .npm-cache