Authentication Commands
login
Authenticate with your BrainGrid account using OAuth2.
Opens your browser for authentication. Once complete, your credentials are stored locally.
whoami
Display information about the currently authenticated user.
Shows your username, email, and account details.
logout
Sign out from your BrainGrid account.
Removes stored authentication credentials from your local machine.
Initialization Commands
init
Initialize a BrainGrid project in the current directory.
# Interactive wizard
braingrid init
# Specify project directly
braingrid init --project PROJ-123
# Skip confirmation prompts
braingrid init --force
.braingrid/project.json file linking your local directory to a BrainGrid project.
Options:
--project <id> - Specify the project ID to link--force - Skip confirmation prompts
Project Commands
project list
List all accessible projects.
# Default table format
braingrid project list
# JSON format with pagination
braingrid project list --format json --page 1 --limit 20
--format <type> - Output format: table, json, xml, markdown--page <number> - Page number for pagination (default: 1)--limit <number> - Results per page (default: 20)
project show
Display details for a specific project.
# Show initialized project
braingrid project show
# Show specific project by ID
braingrid project show PROJ-123
# Show project by repository
braingrid project show --repository "owner/repo"
--repository <string> - GitHub repository in format “owner/name”
project create
Create a new project.
braingrid project create --name "My Project" \
--description "Project description" \
--repository "owner/repo-name"
--name <string> - Project name (required)--description <string> - Project description (optional)--repository <string> - GitHub repository (optional)
project update
Update an existing project.
# Update project name
braingrid project update PROJ-123 --name "New Name"
# Update description
braingrid project update PROJ-123 --description "Updated description"
--name <string> - New project name--description <string> - New project description
project delete
Delete a project.
# With confirmation prompt
braingrid project delete PROJ-123
# Skip confirmation
braingrid project delete PROJ-123 --force
--force - Skip confirmation prompt
Deleting a project also deletes all associated requirements and tasks. This action cannot be undone.
Requirement Commands
specify
Create an AI-refined requirement from a natural language prompt.
# Create requirement in current project
braingrid specify --prompt "Add user authentication with OAuth2"
# Create in specific project
braingrid specify -p PROJ-123 --prompt "Implement dark mode toggle"
# JSON output for scripting
braingrid specify --prompt "Add email notifications" --format json
-p, --project <id> - Target project (defaults to initialized project)--prompt <string> - Natural language description (required)--format <type> - Output format: table, json, xml, markdown
The specify command uses AI to refine your prompt into a structured requirement with clear scope, acceptance criteria, and technical considerations.
requirement list
List all requirements in a project.
# List all requirements
braingrid requirement list
# Filter by status
braingrid requirement list --status IN_PROGRESS
# JSON format
braingrid requirement list --format json
--status <status> - Filter by status: IDEA, PLANNED, IN_PROGRESS, REVIEW, COMPLETED, CANCELLED--format <type> - Output format: table, json, xml, markdown
requirement show
Display details for a specific requirement.
# Auto-detect from git branch (e.g., feature/REQ-123-auth)
braingrid requirement show
# Show specific requirement
braingrid requirement show REQ-123
# JSON format for scripting
braingrid requirement show REQ-123 --format json
--format <type> - Output format: table, json, xml, markdown
requirement create
Manually create a requirement without AI refinement.
braingrid requirement create --name "Implement feature X" \
--content "Detailed description here"
--name <string> - Requirement name (required)--content <string> - Detailed description (optional)
requirement update
Update an existing requirement.
# Update status
braingrid requirement update REQ-123 --status IN_PROGRESS
# Update name
braingrid requirement update REQ-123 --name "Updated Name"
# Update content
braingrid requirement update REQ-123 --content "New description"
--status <status> - New status--name <string> - New name--content <string> - New content
requirement delete
Delete a requirement and all associated tasks.
# With confirmation prompt
braingrid requirement delete REQ-123
# Skip confirmation
braingrid requirement delete REQ-123 --force
--force - Skip confirmation prompt
requirement build
Generate a complete implementation plan with all task details.
# Markdown format (default, perfect for AI agents)
braingrid requirement build REQ-123
# JSON format for tooling
braingrid requirement build REQ-123 --format json
# Auto-detect requirement from branch
braingrid requirement build --format markdown
--format <type> - Output format: markdown, json, xml
requirement create-branch
Create a git branch for a requirement via the GitHub API.
# Auto-detect requirement from current context
braingrid requirement create-branch
# Create branch for specific requirement
braingrid requirement create-branch REQ-123
{username}/REQ-123-slugified-name and creates the branch on GitHub.
This command requires a GitHub repository to be linked to your project. The branch is created remotely via the GitHub API.
requirement review
Stream an AI-powered acceptance review for a pull request.
# Auto-detect PR from current branch
braingrid requirement review
# Review specific requirement
braingrid requirement review REQ-123
Task Commands
task list
List all tasks for a requirement.
# Auto-detect requirement from git branch
braingrid task list
# List tasks for specific requirement
braingrid task list -r REQ-123
# Markdown format for AI context
braingrid task list -r REQ-123 --format markdown
# JSON for scripting
braingrid task list -r REQ-123 --format json
-r, --requirement <id> - Requirement ID (auto-detected from branch if not specified)--format <type> - Output format: table, json, xml, markdown
task show
Display details for a specific task.
# Auto-detect first in-progress or planned task
braingrid task show
# Show specific task
braingrid task show TASK-456
# JSON format for scripting
braingrid task show TASK-456 --format json
--format <type> - Output format: table, json, xml, markdown
When called without a task ID, shows the first in-progress task. If none are in progress, shows the first planned task.
task create
Manually create a task.
braingrid task create -r REQ-123 \
--title "Implement OAuth2 login flow" \
--content "Create login endpoint and integrate with provider"
-r, --requirement <id> - Parent requirement ID (required)--title <string> - Task title (required)--content <string> - Task description (optional)
task update
Update a task’s status, title, or content.
# Auto-detect current task and update status
braingrid task update --status COMPLETED
# Update specific task status
braingrid task update TASK-456 --status COMPLETED
# Update title
braingrid task update TASK-456 --title "New title"
# Update content
braingrid task update TASK-456 --content "Updated description"
--status <status> - New status: PLANNED, IN_PROGRESS, COMPLETED, CANCELLED--title <string> - New title--content <string> - New content
When called without a task ID, updates the first in-progress task. If none are in progress, updates the first planned task.
task delete
Delete a task.
# With confirmation prompt
braingrid task delete TASK-456
# Skip confirmation
braingrid task delete TASK-456 --force
--force - Skip confirmation prompt
task specify
Create a single AI-refined task from a description.
# Create task with AI refinement
braingrid task specify "Add input validation for email field"
# Specify for a specific requirement
braingrid task specify -r REQ-123 "Implement rate limiting on API endpoints"
-r, --requirement <id> - Parent requirement ID (auto-detected from branch if not specified)
The task specify command creates individual tasks with AI refinement. It’s context-aware and understands existing task dependencies when adding to a requirement that already has tasks.
Utility Commands
status
Display CLI configuration and status.
Shows authentication status, current project, CLI version, and configuration details.
update
Update the CLI to the latest version.
# Check for updates and install
braingrid update
# Check for updates without installing
braingrid update --check
--check - Only check for updates, don’t install
completion
Set up shell autocompletion for the CLI.
# Interactive setup (recommended)
braingrid completion --setup
# Add to ~/.bashrc
eval "$(braingrid completion bash)"
—version
Display the CLI version.
—help
Display help information.
# General help
braingrid --help
# Command-specific help
braingrid project --help
braingrid requirement build --help
Status Flows
Requirement Status Flow
Requirements progress through the following states:
IDEA → PLANNED → IN_PROGRESS → REVIEW → COMPLETED
↓
CANCELLED
- IDEA - Initial concept or feature request
- PLANNED - Refined and ready for implementation
- IN_PROGRESS - Active development
- REVIEW - Under review or testing
- COMPLETED - Successfully implemented
- CANCELLED - No longer needed
Task Status Flow
Tasks have a simpler workflow:
PLANNED → IN_PROGRESS → COMPLETED
↓
CANCELLED
- PLANNED - Ready to be worked on
- IN_PROGRESS - Currently being implemented
- COMPLETED - Successfully finished
- CANCELLED - No longer needed
All commands accept multiple ID formats for convenience:
- Canonical:
REQ-456, TASK-123, PROJ-789
- Lowercase:
req-456, task-123, proj-789
- Numeric:
456, 123, 789
- UUID: Full UUID strings
Examples:
# All of these are equivalent
braingrid requirement show REQ-123
braingrid requirement show req-123
braingrid requirement show 123
braingrid requirement show 550e8400-e29b-41d4-a716-446655440000
Table (Default)
Human-readable ASCII tables for terminal viewing.
JSON
Machine-readable format for scripting and automation.
braingrid project list --format json
XML
Structured data for enterprise integrations.
braingrid project list --format xml
Markdown
Rich formatted output optimized for AI agents and documentation.
braingrid task list -r REQ-123 --format markdown
Use markdown format when providing task context to AI coding agents. It includes all necessary details in a format that’s easy for AI to parse and understand.
Common Patterns
Complete Feature Development Workflow
# 1. Create and refine requirement
braingrid specify --prompt "Add payment integration with Stripe"
# → Creates REQ-42
# 2. Create feature branch via GitHub API
braingrid requirement create-branch REQ-42
# → Creates nico/REQ-42-stripe-integration
# 4. Check out the branch locally
git fetch && git checkout nico/REQ-42-stripe-integration
# 5. Get full context for AI agent
braingrid requirement build --format markdown
# 6. Work through tasks (auto-detects current task)
braingrid task update --status IN_PROGRESS
# ... implement task ...
braingrid task update --status COMPLETED
# 7. Create PR and get AI review
braingrid requirement review
Quick Status Check
# Check your current context
braingrid status
# View current requirement (from branch)
braingrid requirement show
# List remaining tasks
braingrid task list -r REQ-42
CI/CD Integration
# Get requirement data in CI pipeline
REQ_DATA=$(braingrid requirement show REQ-42 --format json)
# List completed tasks for release notes
braingrid task list -r REQ-42 --format markdown > RELEASE_NOTES.md
