Skip to main content

​
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

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

​
Time-Based Scheduling

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

​
Hierarchical Issues

# 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

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

​
Special Characters in Descriptions

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

Build docs developers (and LLMs) love

Get started for freeTalk to us