> ## Documentation Index
> Fetch the complete documentation index at: https://abil-shrestha-tracer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# tracer create

> Create a new issue in your tracer database

## Syntax

```bash theme={null}
tracer create [TITLE] [OPTIONS]
```

## Description

Creates a new issue with the specified title and options. Issues are automatically assigned sequential IDs based on your configured prefix.

## Arguments

**TITLE** `string` *required*

The issue title. Wrap in quotes if it contains spaces.

## Options

**-d, --description** `string`

Issue description with additional details.

**-p, --priority** `integer` (default: 2)

Priority level (0=highest, 4=lowest).

**-t, --issue-type** `enum` (default: task)

Issue type. Valid values: `bug`, `feature`, `task`, `epic`, `chore`.

**-a, --assignee** `string`

Assign the issue to a specific person or agent.

**-l, --labels** `string`

Comma-separated labels to attach to the issue.

**--deps** `string`

Comma-separated dependencies. Format: `type:id` or just `id` for blocks type.

Types: `blocks`, `related`, `parent-child`, `discovered-from`.

**--id** `string`

Explicit issue ID to avoid collisions. Use with caution.

**-f, --file** `string`

Create from markdown file (not yet implemented).

**--json** `boolean`

Output the created issue in JSON format.

## Examples

```bash Simple issue theme={null}
tracer create "Fix login bug"
```

```bash High-priority bug theme={null}
tracer create "Critical auth vulnerability" -t bug -p 0
```

```bash Feature with description theme={null}
tracer create "Add user profile page" \
  -t feature \
  -p 1 \
  -d "Users should be able to view and edit their profile"
```

```bash With labels and assignee theme={null}
tracer create "Refactor API client" \
  -t chore \
  -l "refactor,technical-debt" \
  -a "agent-1"
```

```bash With dependencies theme={null}
tracer create "Deploy to production" \
  -p 1 \
  --deps "blocks:bd-5,blocks:bd-7"
```

```bash Create epic with subtasks theme={null}
# Create the epic
EPIC_ID=$(tracer create "User authentication system" -t epic -p 0 --json | jq -r '.id')

# Create subtasks
tracer create "Design auth schema" -t task --deps "parent-child:$EPIC_ID"
tracer create "Implement login endpoint" -t task --deps "parent-child:$EPIC_ID"
```

## Output Format

### Human-readable

```
✓ Created issue bd-42 Fix login bug
  Labels: security, urgent
  Dependencies: blocks:bd-41
```

### JSON (with --json flag)

```json theme={null}
{
  "id": "bd-42",
  "title": "Fix login bug",
  "description": "",
  "design": "",
  "acceptance_criteria": "",
  "notes": "",
  "status": "open",
  "priority": 0,
  "issue_type": "bug",
  "assignee": "",
  "estimated_minutes": null,
  "created_at": "2026-03-04T10:30:00Z",
  "updated_at": "2026-03-04T10:30:00Z",
  "closed_at": null,
  "external_ref": null,
  "dependencies": []
}
```

> [!NOTE]
>
> Issues are created with status `open` by default. Use `tracer update` to change the status to `in_progress` when you start working on them.

> [!TIP]
>
> Use the `--json` flag to capture the issue ID in scripts:
>
> ```bash theme={null}
> ISSUE_ID=$(tracer create "My task" --json | jq -r '.id')
> echo "Created: $ISSUE_ID"
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.