> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt > Use this file to discover all available pages before exploring further. # bd create > Create new issues with rich metadata and dependencies ## Usage ```bash theme={null} 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 Issue title (required unless using `--file`). Can be provided as positional argument or via `--title` flag. ### Core Flags Issue title (alternative to positional argument) Detailed description of the issue. Use `-` to read from stdin for descriptions with special characters. Priority level: 0-4 or P0-P4 (P0=critical, P4=backlog) Issue type: `bug`, `feature`, `task`, `epic`, `chore`, `decision`. Aliases: `feat`→`feature`, `dec`/`adr`→`decision` Assign issue to user Comma-separated labels. Repeatable flag. ### Extended Fields Design notes and technical approach Acceptance criteria for completion Additional notes and context Link to specification document Time estimate in minutes (e.g., 60 for 1 hour) ### Dependencies Dependencies in format `type:id` or just `id` for blocks type. Examples: `blocks:bd-20`, `discovered-from:bd-15` Parent issue ID for hierarchical child (e.g., `bd-abc`). Creates parent-child dependency automatically. Spawner issue ID to wait for (creates waits-for dependency for fanout gate) Gate type: `all-children` (wait for all) or `any-children` (wait for first) ### Time Scheduling Due date/time. Formats: `+6h`, `+1d`, `+2w`, `tomorrow`, `next monday`, `2025-01-15` Defer until date (issue hidden from `bd ready` until then). Same formats as `--due` ### Advanced Options Explicit issue ID (e.g., `bd-42` for partitioning) Create issue in a different rig (e.g., `--rig beads`) Create issue in rig by prefix (e.g., `--prefix bd-` or `--prefix beads`) Set custom metadata (JSON string or `@file.json` to read from file) Create as ephemeral (short-lived, subject to TTL compaction) Preview what would be created without actually creating Output only the issue ID (for scripting) Output JSON for agent use ## Examples ### Basic Creation ```bash Simple theme={null} bd create "Fix login bug" \ --description="Users cannot log in after password reset" \ --type bug \ --priority 1 \ --json ``` ```bash With Labels theme={null} bd create "Add dark mode" \ --description="Implement dark theme for UI" \ --type feature \ --labels ui,accessibility \ --estimate 180 \ --json ``` ```bash With Dependencies theme={null} bd create "Deploy to production" \ --description="Deploy v2.0 release" \ --type task \ --deps blocks:bd-123,blocks:bd-124 \ --json ``` ### Time-Based Scheduling ```bash Due Date theme={null} bd create "Review Q4 metrics" \ --description="Quarterly business review" \ --due "next friday" \ --json ``` ```bash Deferred Task theme={null} bd create "Update dependencies" \ --description="Quarterly dependency updates" \ --defer "+30d" \ --json ``` ### Hierarchical Issues ```bash Parent-Child theme={null} # Create parent epic bd create "User authentication" --type epic --json # Create child task bd create "Implement OAuth" \ --parent bd-abc \ --type task \ --json ``` ```bash Auto-Generated Child ID theme={null} bd create "Subtask" --parent bd-abc --json # Creates bd-abc.1, bd-abc.2, etc. ``` ### Cross-Rig Creation ```bash Create in Different Rig theme={null} bd create "Configure monitoring" \ --rig gastown \ --description="Set up alerting" \ --json ``` ```bash Auto-Routing by Prefix theme={null} bd create "Task" \ --id gt-xyz \ --description="Auto-routes to gastown rig" \ --json ``` ### Special Characters in Descriptions ```bash Stdin Input theme={null} echo 'Description with `backticks` and "quotes"' | \ bd create "Title" --description=- --json ``` ```bash From File theme={null} cat description.txt | \ bd create "Issue title" --description=- --json ``` ### Bulk Creation ```bash theme={null} bd create --file issues.md ``` Markdown format: ```markdown theme={null} # Issue Title 1 Description for first issue ## Design Technical approach --- # Issue Title 2 Description for second issue ``` ## JSON Output With `--json` flag: ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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`](/cli/update) - Modify existing issues * [`bd show`](/cli/show) - View issue details * [`bd dep add`](/cli/dep) - Add dependencies after creation * [`bd list`](/cli/list) - Search for similar issues