> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braingrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Reference

> Complete reference for all BrainGrid CLI commands

## Authentication Commands

### login

Authenticate with your BrainGrid account using OAuth2.

```bash theme={null}
braingrid login
```

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

### whoami

Display information about the currently authenticated user.

```bash theme={null}
braingrid whoami
```

Shows your username, email, and account details.

### logout

Sign out from your BrainGrid account.

```bash theme={null}
braingrid logout
```

Removes stored authentication credentials from your local machine.

## Initialization Commands

### init

Initialize a BrainGrid project in the current directory.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
# With confirmation prompt
braingrid project delete PROJ-123

# Skip confirmation
braingrid project delete PROJ-123 --force
```

**Options:**

* `--force` - Skip confirmation prompt

<Warning>
  Deleting a project also deletes all associated requirements and tasks. This action cannot be undone.
</Warning>

## Requirement Commands

### specify

Create an AI-refined requirement from a natural language prompt.

```bash theme={null}
# 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`

<Note>
  The `specify` command uses AI to refine your prompt into a structured requirement with clear scope, acceptance criteria, and technical considerations.
</Note>

### requirement list

List all requirements in a project.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

<Note>
  This command requires a GitHub repository to be linked to your project. The branch is created remotely via the GitHub API.
</Note>

### requirement review

Stream an AI-powered acceptance review for a pull request.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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`

<Note>
  When called without a task ID, shows the first in-progress task. If none are in progress, shows the first planned task.
</Note>

### task create

Manually create a task.

```bash theme={null}
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.

```bash theme={null}
# 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

<Note>
  When called without a task ID, updates the first in-progress task. If none are in progress, updates the first planned task.
</Note>

### task delete

Delete a task.

```bash theme={null}
# 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.

```bash theme={null}
# 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)

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

## Utility Commands

### status

Display CLI configuration and status.

```bash theme={null}
braingrid status
```

Shows authentication status, current project, CLI version, and configuration details.

### update

Update the CLI to the latest version.

```bash theme={null}
# 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.

```bash theme={null}
# 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:**

<CodeGroup>
  ```bash Bash theme={null}
  # Add to ~/.bashrc
  eval "$(braingrid completion bash)"
  ```

  ```bash Zsh theme={null}
  # Add to ~/.zshrc
  eval "$(braingrid completion zsh)"
  ```
</CodeGroup>

### --version

Display the CLI version.

```bash theme={null}
braingrid --version
```

### --help

Display help information.

```bash theme={null}
# 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:

```bash theme={null}
# 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.

```bash theme={null}
braingrid project list
```

### JSON

Machine-readable format for scripting and automation.

```bash theme={null}
braingrid project list --format json
```

### XML

Structured data for enterprise integrations.

```bash theme={null}
braingrid project list --format xml
```

### Markdown

Rich formatted output optimized for AI agents and documentation.

```bash theme={null}
braingrid task list -r REQ-123 --format markdown
```

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

## Common Patterns

### Complete Feature Development Workflow

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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
```