BlocPad CLI

Product Introduction

1. Definition: BlocPad CLI is a specialized command-line interface (CLI) tool designed for developers and technical teams. It integrates directly with the BlocPad platform, functioning as a secure bridge to extract structured project and task context for use in automation scripts and AI-powered coding assistants (like Cursor, Codex CLI, Claude CLI, GitHub Copilot).
2. Core Value Proposition: BlocPad CLI eliminates the ambiguity inherent in AI coding by providing exact, scoped task context. It transforms BlocPad work items into executable instructions, enabling faster AI-generated output with significantly fewer correction cycles and ensuring automation scripts operate on reliable, up-to-date data.

Main Features

1. Explicit Scope Management:
   • How it works: The CLI operates within a defined active project and task context. Commands like blocpad tasks focus <TASK_ID> require specifying a task, ensuring exported context is always relevant to a specific unit of work. This prevents AI hallucinations or script errors caused by ambiguous scope.
   • Technology: Context is managed locally and passed via command arguments or environment variables (BLOCPAD_PROJECT_ID, BLOCPAD_TASK_ID).
2. Automation & LLM-Optimized Exports:
   • How it works: BlocPad CLI offers dual export formats. --json provides stable, parseable output suitable for scripting and CI/CD pipelines. --md generates Markdown-formatted context ideal for direct copy/paste into AI coding assistant prompts, preserving hierarchy and detail without exposing sensitive data.
   • Technology: Utilizes structured data serialization (JSON) and lightweight markup (Markdown) for interoperability. Strict separation of stdout (machine-readable data) and stderr (prompts/errors) ensures clean parsing.
3. Safe by Default & Secure Token Handling:
   • How it works: All context exports (tasks list, tasks show, tasks focus) are inherently read-only, preventing accidental modifications to BlocPad data. Personal Access Tokens (bp_pat_...) are securely stored in the user's local config directory (e.g., ~/Library/Application Support/blocpad/ on macOS) and can be overridden at runtime via --token or BLOCPAD_TOKEN env var, avoiding hardcoding secrets.
   • Technology: Secure local storage mechanisms (OS-specific keychains not mentioned, but config files are standard) and runtime overrides following security best practices for CLI tools.
4. Agent Workflow Orchestration:
   • How it works: Commands like blocpad tasks next <TASK_ID> --json and blocpad tasks focus <TASK_ID> --md are specifically designed for AI agent workflows. They help agents identify the next actionable "leaf task" (a task with no incomplete subtasks) and export its full context, enabling autonomous task progression within defined boundaries.
   • Technology: Hierarchical task traversal algorithms (using parentTaskId/parent_task_id fields) and context aggregation optimized for AI agent instructions.

Problems Solved

1. Pain Point: Context Fragmentation in AI Coding. Traditional AI tools guess intent from incomplete prompts, leading to irrelevant, incorrect, or overly broad outputs requiring significant manual correction. BlocPad CLI solves this by feeding AI tools the exact, scoped context from BlocPad tasks.
2. Target Audience:
   • Developers using AI Pair Programmers: Specifically those leveraging tools like Cursor, Codex CLI, Claude CLI, or GitHub Copilot.
   • Engineering Teams: Seeking to standardize task context and integrate BlocPad data into automated workflows (testing, builds, deployments).
   • Technical Leads/Managers: Needing reliable, auditable context for AI-generated code and automation scripts.
3. Use Cases:
   • Reducing AI Correction Loops: Paste exported Markdown task context into an AI chat (e.g., Cursor Chat) for highly accurate implementation suggestions.
   • Scripting Task Status: Use blocpad tasks list --json in a CI pipeline script to check task completion status before deployment.
   • Automating Context Provisioning: Integrate blocpad tasks focus into a custom script that preps context for an AI agent before execution.
   • Enforcing Workflow: Guide AI agents to work only on independent "leaf tasks" using the next and focus commands, adhering to a hierarchical workflow.

Unique Advantages

1. Differentiation: Unlike generic CLI tools or AI assistants operating in isolation, BlocPad CLI is purpose-built to connect a structured work management platform (BlocPad) directly with coding tools and AI agents. It uniquely enforces scope and provides safe, optimized exports, unlike manual copy/paste or screen-sharing context transfer.
2. Key Innovation: The strict separation of concerns between context provisioning and code execution, combined with safe, scoped exports (--json/--md) and AI-agent specific commands (next, focus), creates a novel workflow. This ensures AI tools act as predictable "task workers" operating on verified instructions, not guesswork.

Frequently Asked Questions (FAQ)

1. Is BlocPad CLI safe to use with AI tools like ChatGPT or Claude? Yes, BlocPad CLI is designed for safe AI integration. Its --md export provides rich, read-only context perfect for prompts, and the critical rule is to never share your bp_pat_... token with any LLM – paste only the exported Markdown content.
2. How does BlocPad CLI ensure JSON output works reliably in scripts? BlocPad CLI rigorously separates output streams. When using --json, the only content on stdout is valid JSON, making it instantly parseable by scripts (jq, etc.). Any prompts, warnings, or errors are directed to stderr.
3. Where is my BlocPad CLI authentication token stored, and is it secure? Your Personal Access Token is stored locally in a configuration file within your OS user config directory (e.g., ~/Library/Application Support/blocpad/ on macOS). While generally secure, avoid hardcoding tokens in scripts; use blocpad auth login or runtime overrides (--token, BLOCPAD_TOKEN).
4. Can BlocPad CLI modify my BlocPad tasks or projects? No. BlocPad CLI is fundamentally read-only for task and project data. Its core function is safe context export (list, show, tree, next, focus). It cannot create, update, or delete BlocPad items.
5. How do I integrate BlocPad CLI with GitHub Copilot or Cursor? Export the relevant task context using blocpad tasks focus <TASK_ID> --md. For Copilot, paste this Markdown into your project's .github/copilot-instructions.md file. For Cursor, paste it directly into the chat or save the rules in a .cursorrules file as shown in the Quickstart guide.