# jira-cli Detailed Reference

**Assumptions:** Already installed/configured, `JIRA_API_TOKEN` set, `jira init` complete

**Project flag:** Always use `-p PROJ` to specify project explicitly (don't rely on defaults)

---

# Core Workflow: Working on Issue

```bash
# User: "Work on PROJ-123"
jira issue view -p PROJ PROJ-123                          # Read requirements
jira issue assign PROJ-123 $(jira me)                     # Assign to user
jira issue move PROJ-123 "In Progress"                    # Update status
# ... implement code ...
jira issue comment add PROJ-123 "Fixed in $(git rev-parse --short HEAD)"
jira issue move PROJ-123 "Done"                           # Close
```

---

# Command Syntax by Intent

## Query Issues

**By filters:**
```bash
jira issue list -p PROJ -tBug -aCurrentUser -s"To Do"     # Type, assignee, status
jira issue list -p PROJ -yHigh -lbackend --created week   # Priority, label, date
```

**By JQL (complex queries):**
```bash
jira issue list -p PROJ --jql 'assignee=currentUser() AND status!="Done"'
jira issue list -p PROJ --jql 'priority IN (High,Critical) AND created >= -7d'
```

**Common patterns:**
- My bugs: `jira issue list -p PROJ -tBug -aCurrentUser`
- High priority work: `jira issue list -p PROJ -yHigh -s"To Do"`
- Recent activity: `jira issue list -p PROJ -aCurrentUser --updated -1d`

## View Issue

```bash
jira issue view -p PROJ PROJ-123                          # Basic view
jira issue view -p PROJ PROJ-123 --comments 50            # With comments
jira issue view -p PROJ PROJ-123 --raw                    # JSON output
jira open PROJ-123                                        # Open in browser
```

## Create Issue

```bash
jira issue create -p PROJ -tBug -s"Summary" -yHigh -lbackend
jira issue create -p PROJ -tStory -s"Feature name"
```

## Update Issue

```bash
jira issue assign PROJ-123 $(jira me)                     # Assign to self
jira issue assign PROJ-123 "user@example.com"             # Assign to user
jira issue move PROJ-123 "In Progress"                    # Change status
jira issue comment add PROJ-123 "Comment text"            # Add comment
jira issue edit -p PROJ PROJ-123 -yHigh -lurgent          # Edit priority/labels
```

---

# Efficient Data Extraction

**Principle:** Extract only needed fields to minimize context.

```bash
# Get single field via jq
jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.status.name'
jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.assignee.displayName'

# Get specific columns only
jira issue list -p PROJ --plain --no-headers --columns KEY
jira issue list -p PROJ --plain --columns KEY,STATUS,ASSIGNEE

# Check existence
jira issue view -p PROJ PROJ-123 --plain > /dev/null 2>&1 && echo "exists"
```

---

# JQL Reference

**Structure:** `jira issue list -p PROJ --jql 'FIELD OPERATOR VALUE'`

**Operators:** `=`, `!=`, `IN`, `>`, `<`, `>=`, `<=`

**Functions:**
- `currentUser()` - Current logged-in user
- `openSprints()` - Active sprints
- `startOfWeek()`, `startOfDay()` - Date functions

**Date formats:**
- Relative: `-7d`, `-2w`, `-1m`
- Absolute: `"2023-12-01"`

**Examples:**
```bash
# Multiple conditions
jira issue list -p PROJ --jql 'project=PROJ AND assignee=currentUser() AND status!="Done"'

# Date ranges
jira issue list -p PROJ --jql 'created >= -7d AND updated >= startOfWeek()'

# IN operator
jira issue list -p PROJ --jql 'status IN ("To Do","In Progress")'
```

---

# Output Formats

**For display:** Default table format
**For parsing:** `--plain --no-headers --columns KEY`
**For extraction:** `--raw` with `jq`

```bash
# Table (default)
jira issue list -p PROJ

# Plain text for parsing
jira issue list -p PROJ --plain --no-headers --columns KEY

# JSON for field extraction
jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.summary'
```

---

# Filter Flags Reference

| Flag | Purpose | Example |
|------|---------|---------|
| `-t` | Type | `-tBug`, `-tStory`, `-tTask` |
| `-s` | Status | `-s"To Do"`, `-s"In Progress"` |
| `-y` | Priority | `-yHigh`, `-yMedium`, `-yLow` |
| `-a` | Assignee | `-aCurrentUser`, `-a"user@example.com"` |
| `-l` | Label | `-lbackend`, `-lurgent,critical` |
| `--created` | Created date | `--created today`, `--created week`, `--created 2023-12-01` |
| `--updated` | Updated date | `--updated -7d` |
| `--jql` | Raw JQL query | `--jql 'custom query'` |

---

# User Intent → Command Mapping

| User Says | Command |
|-----------|---------|
| "Work on PROJ-123" | `jira issue view -p PROJ PROJ-123` |
| "What bugs do I have?" | `jira issue list -p PROJ -tBug -aCurrentUser` |
| "What should I work on?" | `jira issue list -p PROJ -yHigh -s"To Do"` |
| "Create bug for X" | `jira issue create -p PROJ -tBug -s"X"` |
| "Close PROJ-123" | `jira issue move PROJ-123 "Done"` |
| "Add comment to PROJ-123" | `jira issue comment add PROJ-123 "text"` |
| "What did I work on yesterday?" | `jira issue list -p PROJ -aCurrentUser --updated -1d` |

---

# Best Practices

1. **Always specify project:** Use `-p PROJ` flag explicitly
2. **Extract minimal data:** Use `--raw | jq` for specific fields instead of reading full issue
3. **Filter before reading:** Narrow with queries, then read details
4. **Use plain output for scripts:** `--plain --no-headers --columns KEY`
5. **Proactive updates:** After code changes, offer to add commits/close issues
6. **Rate limits:** Add `sleep 0.5` between bulk operations

---

# Troubleshooting

**Auth errors:** Check `echo $JIRA_API_TOKEN` and `cat ~/.config/.jira/.config.yml`

**Issue not found:** Verify project key correct: `jira issue view -p PROJ PROJ-123 --plain`

**Rate limits:** Add delays between bulk operations, use more specific queries