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
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 breakdown
Break a requirement into AI-generated tasks.
# Auto-detect from git branch
braingrid requirement breakdown
# Specific requirement
braingrid requirement breakdown REQ-123
The breakdown command analyzes your requirement and generates task prompts that include context, acceptance criteria, and implementation guidance for AI agents.
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
Task Commands
task list
List all tasks for a requirement.
# List tasks for 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 (required)--format <type> - Output format: table, json, xml, markdown
task show
Display details for a specific task.
braingrid task show TASK-456
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.
# Update status (most common)
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
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
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
—version
Display the CLI version.
—help
Display help information.
# General help
braingrid --help
# Command-specific help
braingrid project --help
braingrid requirement breakdown --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 breakdown
- 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. Break into tasks
braingrid requirement breakdown REQ-42
# → Creates TASK-1 through TASK-8
# 3. Create feature branch
git checkout -b feature/REQ-42-stripe-integration
# 4. Get full context for AI agent
braingrid requirement build REQ-42 --format markdown
# 5. Work through tasks, updating status
braingrid task update TASK-1 --status IN_PROGRESS
# ... implement task ...
braingrid task update TASK-1 --status COMPLETED
# 6. Mark requirement complete
braingrid requirement update REQ-42 --status COMPLETED
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
