How to Create a New Task with a Specific Priority Using the Beads CLI

Use the bd create command with the -p or --priority flag followed by a numeric value from 0 (highest) to 4 (lowest) to assign a priority level when creating a new task.

The Beads command-line interface provides a streamlined method for managing work items directly from the terminal in the gastownhall/beads repository. When creating new tasks, you can immediately assign priority levels using numeric flags to ensure critical items receive appropriate attention. This guide demonstrates the exact syntax and source file locations where the priority functionality is implemented.

Understanding the Priority Flag Syntax

The priority flag is documented in the CLI reference at website/versioned_docs/version-1.0.0/cli-reference/issues.md, where the --priority, -p option accepts integer values ranging from 0 to 4. According to the source documentation, 0 represents the highest priority (critical), while 4 represents the lowest priority (minimal), creating a five-tier severity system for issue classification.

Creating a Task with Priority from the Command Line

To create a new task with a specific priority, combine the bd create command with the task type flag and priority value. The basic structure requires a title string followed by the -t task designation and the -p flag with your chosen numeric level.

bd create "Set up database" -t task -p 1

This command creates a high-priority task (level 1) as illustrated in the quick-start guide at website/versioned_docs/version-1.0.0/intro.md (line 36). The -t flag specifies the work item type, while -p immediately assigns the priority tier during creation.

Practical Examples for Common Use Cases

High-Priority Task Creation

For urgent development tasks that require immediate attention, use priority level 1 or 0. The following example demonstrates creating a high-priority infrastructure task with an optional description:

bd create "Implement caching layer" -t task -p 1 --description="Cache API responses for 5 min"

Critical Bug Reports

Priority flags work universally across all issue types, not just tasks. As shown in website/versioned_docs/version-1.0.0/core-concepts/issues.md (line 57), you can assign priority 0 to critical bugs:

bd create "Fix login bug" -t bug -p 0

This creates a critical-priority bug issue, ensuring it appears at the top of backlog queues.

Combining Priority with Long-Form Flags

For shell scripts or automated workflows where readability is essential, use the long-form --priority flag combined with --type:

bd create "Add OAuth support" --type task --priority 2 --json

The --json flag outputs the creation result in JSON format, useful for CI/CD pipelines that need to parse the response programmatically.

Summary

• Use bd create with -p or --priority followed by 0-4 to set task priority immediately upon creation
• Priority 0 indicates critical (highest) priority, while 4 indicates minimal (lowest) priority
• The flag works with all issue types including tasks, bugs, and features as documented in the CLI reference
• Source examples are located in website/versioned_docs/version-1.0.0/intro.md and website/versioned_docs/version-1.0.0/core-concepts/issues.md

Frequently Asked Questions

What numeric values correspond to priority levels in Beads?

Beads uses a 0-4 integer scale where 0 represents the highest (critical) priority and 4 represents the lowest (minimal) priority. This five-tier system allows for granular classification of work item urgency directly from the command line.

Can I set priority when creating issue types other than tasks?

Yes, the -p flag works universally across all issue types. As implemented in the gastownhall/beads source code, you can assign priorities to bugs, features, and other work items using the same syntax demonstrated for tasks in the core concepts documentation.

Is there a default priority if I omit the -p flag?

The source documentation does not specify a default priority value when the flag is omitted. To ensure consistent priority assignment, explicitly include the -p flag followed by your desired numeric level (0-4) when running bd create.

How do I verify the priority was set correctly after creation?

Use the --json flag with your bd create command to receive structured output confirming all assigned attributes, or query the created issue using bd show followed by the issue ID to verify the priority field in the returned metadata.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}