bd create

Create new issues with rich metadata and dependencies

Usage

bd create [title] [flags]
bd create --file issues.md

Description

Create a new issue with title, description, priority, type, labels, and dependencies. Issues can be created individually or in bulk from markdown files.

Parameters

title · string

Issue title (required unless using --file). Can be provided as positional argument or via --title flag.

Core Flags

--title · string

Issue title (alternative to positional argument)

--description · string

Detailed description of the issue. Use - to read from stdin for descriptions with special characters.

--priority · string · default: "2"

Priority level: 0-4 or P0-P4 (P0=critical, P4=backlog)

--type · string · default: "task"

Issue type: bug, feature, task, epic, chore, decision. Aliases: feat→feature, dec/adr→decision

--assignee · string

Assign issue to user

--labels · string[]

Comma-separated labels. Repeatable flag.

Extended Fields

--design · string

Design notes and technical approach

--acceptance · string

Acceptance criteria for completion

--notes · string

Additional notes and context

--spec-id · string

Link to specification document

--estimate · integer

Time estimate in minutes (e.g., 60 for 1 hour)

Dependencies

--deps · string[]

Dependencies in format type:id or just id for blocks type. Examples: blocks:bd-20, discovered-from:bd-15

--parent · string

Parent issue ID for hierarchical child (e.g., bd-abc). Creates parent-child dependency automatically.

--waits-for · string

Spawner issue ID to wait for (creates waits-for dependency for fanout gate)

--waits-for-gate · string · default: "all-children"

Gate type: all-children (wait for all) or any-children (wait for first)

Time Scheduling

--due · string

Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15

--defer · string

Defer until date (issue hidden from bd ready until then). Same formats as --due

Advanced Options

--id · string

Explicit issue ID (e.g., bd-42 for partitioning)

--rig · string

Create issue in a different rig (e.g., --rig beads)

--prefix · string

Create issue in rig by prefix (e.g., --prefix bd- or --prefix beads)

--metadata · string

Set custom metadata (JSON string or @file.json to read from file)

--ephemeral · boolean

Create as ephemeral (short-lived, subject to TTL compaction)

--dry-run · boolean

Preview what would be created without actually creating

--silent · boolean

Output only the issue ID (for scripting)

--json · boolean

Output JSON for agent use

Examples

Basic Creation

Simple

bd create "Fix login bug" \
  --description="Users cannot log in after password reset" \
  --type bug \
  --priority 1 \
  --json

Time-Based Scheduling

Due Date

bd create "Review Q4 metrics" \
  --description="Quarterly business review" \
  --due "next friday" \
  --json

Hierarchical Issues

Parent-Child

# Create parent epic
bd create "User authentication" --type epic --json

# Create child task
bd create "Implement OAuth" \
  --parent bd-abc \
  --type task \
  --json

Cross-Rig Creation

Create in Different Rig

bd create "Configure monitoring" \
  --rig gastown \
  --description="Set up alerting" \
  --json

Special Characters in Descriptions

Stdin Input

echo 'Description with `backticks` and "quotes"' | \
  bd create "Title" --description=- --json

Bulk Creation

bd create --file issues.md

Markdown format:

# Issue Title 1
Description for first issue

## Design
Technical approach

---

# Issue Title 2  
Description for second issue

JSON Output

With --json flag:

{
  "id": "bd-abc123",
  "title": "Fix login bug",
  "description": "Users cannot log in after password reset",
  "status": "open",
  "priority": 1,
  "issue_type": "bug",
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "agent-name",
  "owner": "project-name"
}

Validation

Template Validation

Use --validate to enforce issue type templates:

bd create "Bug report" \
  --type bug \
  --validate \
  --description="Missing required sections" \
  --json
# Error: bug template requires: Steps to Reproduce, Expected, Actual

Prefix Validation

Explicit IDs must match database prefix:

bd create "Task" --id gt-xyz --json
# Error: prefix 'gt-' not allowed (database uses 'bd-')
# Use --force to override

Best Practices

For Agents

1. Always use --json for programmatic parsing
2. Add --silent when only the ID is needed
3. Use --deps discovered-from:parent-id to link discovered work
4. Set --priority based on urgency and impact

For Humans

1. Write descriptive titles that summarize the issue
2. Include context in the description (why, not just what)
3. Add labels for categorization and filtering
4. Link dependencies to track blocking relationships

Warnings

The CLI will warn you about:

• Creating issues without descriptions
• Test issues in production database
• Defer dates in the past
• Creating child of non-existent parent

Related Commands

• bd update - Modify existing issues
• bd show - View issue details
• bd dep add - Add dependencies after creation
• bd list - Search for similar issues