BlocPad CLI (blocpad)

BlocPad CLI is a terminal interface for reading BlocPad context (projects, tasks, pages) and driving a step-by-step execution workflow for engineering agents.

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:tokens

2. Log in:

blocpad auth login --token bp_pat_...

3. Verify:

blocpad auth status
blocpad context show

Fetch task context (for AI tools)

Given a task number (example: 123 or ERS-1), fetch everything needed to start work:

blocpad task ERS-1 --md

If the task is a parent (has subtasks), prefer focusing the next leaf subtask:

blocpad tasks focus ERS-1 --md

Helper commands

Projects:

blocpad projects list --json
blocpad context show --json

Tasks (active project required):

blocpad tasks list --md
blocpad tasks show ERS-1 --md
blocpad tasks comments ERS-1 --md
blocpad tasks breadcrumb ERS-1
blocpad tasks tree ERS-1 --md
blocpad tasks next ERS-1 --json
blocpad tasks focus ERS-1 --md

Pages / Wiki:

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

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`

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, 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

• 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