Command Reference - BrainGrid

Authentication Commands

Authenticate with your BrainGrid account using OAuth2.

braingrid login

Opens your browser for authentication. Once complete, your credentials are stored locally.

whoami

Display information about the currently authenticated user.

braingrid whoami

Shows your username, email, and account details.

logout

Sign out from your BrainGrid account.

braingrid logout

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

Creates a .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

Options:

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

Options:

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

Options:

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

Options:

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

Options:

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

Options:

-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

Options:

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

Options:

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

Options:

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

Options:

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

Options:

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

Options:

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

Automatically generates branch names in the format {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

Analyzes your pull request against the requirement’s acceptance criteria and provides detailed feedback. If no PR is found for the current branch, you’ll be prompted to select one interactively.

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

Options:

-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

Options:

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

Options:

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

Options:

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

Options:

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

Options:

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

braingrid 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

Options:

--check - Only check for updates, don’t install

completion

Set up shell autocompletion for the CLI.

# Interactive setup (recommended)
braingrid completion --setup

This adds autocompletion to your shell configuration. After setup, restart your terminal or source your config file. Manual setup:

# Add to ~/.bashrc
eval "$(braingrid completion bash)"

# Add to ~/.zshrc
eval "$(braingrid completion zsh)"

—version

Display the CLI version.

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

Flexible ID Formats

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

Output Formats

Most commands support multiple output formats:

Table (Default)

Human-readable ASCII tables for terminal viewing.

braingrid project list

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

​Authentication Commands

​login

​whoami

​logout

​Initialization Commands

​init

​Project Commands

​project list

​project show

​project create

​project update

​project delete

​Requirement Commands

​specify

​requirement list

​requirement show

​requirement create

​requirement update

​requirement delete

​requirement build

​requirement create-branch

​requirement review

​Task Commands

​task list

​task show

​task create

​task update

​task delete

​task specify

​Utility Commands

​status

​update

​completion

​—version

​—help

​Status Flows

​Requirement Status Flow

​Task Status Flow

​Flexible ID Formats

​Output Formats

​Table (Default)

​JSON

​XML

​Markdown

​Common Patterns

​Complete Feature Development Workflow

​Quick Status Check

​CI/CD Integration

Authentication Commands

login

whoami

logout

Initialization Commands

init

Project Commands

project list

project show

project create

project update

project delete

Requirement Commands

specify

requirement list

requirement show

requirement create

requirement update

requirement delete

requirement build

requirement create-branch

requirement review

Task Commands

task list

task show

task create

task update

task delete

task specify

Utility Commands

status

update

completion

—version

—help

Status Flows

Requirement Status Flow

Task Status Flow

Flexible ID Formats

Output Formats

Table (Default)

JSON

XML

Markdown

Common Patterns

Complete Feature Development Workflow

Quick Status Check

CI/CD Integration