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

> Easily create a new task with a specific priority using the Beads CLI. Learn how to use the bd create command with the -p flag to set priority levels from 0 to 4.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: how-to-guide
- Published: 2026-04-27

---

**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`](https://github.com/gastownhall/beads/blob/main/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.

```bash
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`](https://github.com/gastownhall/beads/blob/main/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:

```bash
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`](https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.0/core-concepts/issues.md) (line 57), you can assign priority 0 to critical bugs:

```bash
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`:

```bash
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`](https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.0/intro.md) and [`website/versioned_docs/version-1.0.0/core-concepts/issues.md`](https://github.com/gastownhall/beads/blob/main/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.