---
name: imdone-ls
description: List and filter Jira or GitHub issues from the current project. Use
  when the user wants to see issues, find specific issues, or filter by
  favorites/status/time.
user-invocable: true
argument-hint: "[flags] [--query <query>]"
---

# List Issues with imdone ls

Help the user list and filter locally synced issues using `imdone ls` and imdone filter syntax.

## Command Format

```bash
imdone list [OPTIONS]
# or use the alias
imdone ls [OPTIONS]
```

## Common Use Cases

### Basic Listing
- **Compact listing** (default): `imdone ls`
- **Long format with details**: `imdone ls -l`
- **Sort by modification time**: `imdone ls -t`
- **Reverse sort order**: `imdone ls -r`
- **Combine flags**: `imdone ls -ltr` (long format, time-sorted, reversed)

### Filtering
- **Show only favorites**: `imdone ls --fav` or `imdone ls --favorites`
- **Limit results**: `imdone ls --limit 10`
- **Favorites + time sorted**: `imdone ls --fav -t`

### Output Formats
- **JSON**: `imdone ls --format json`
- **YAML**: `imdone ls --format yaml`
- **CSV**: `imdone ls --format csv`
- **Text** (default): `imdone ls --format text`

### Custom Queries

`imdone ls -q` uses imdone filter syntax applied locally against synced issues. It is not JQL and it is not GitHub search syntax.

```bash
# Filter by status
imdone ls -q 'meta.status="In Progress"'

# Filter by assignee
imdone ls -q 'meta.assignedTo="username"'

# Filter by label/tag
imdone ls -q 'tag:bug'

# Filter open issues
imdone ls -q 'meta.status="open"'

# Filter by milestone
imdone ls -q 'meta.milestone="v1.0"'

# Combine filters
imdone ls -q 'meta.status="open" and tag:enhancement'

# Filter pull requests (GitHub-backed issues)
imdone ls -q 'meta.isPullRequest=true'
```

### Verbose Mode
Show the query being executed:
```bash
imdone ls --verbose
imdone ls -q "custom query" --verbose
```

## Workflow Steps

When the user wants to list issues:

1. **Understand the request**: Are they filtering, sorting, or just listing all?

2. **Build the command**:
   - Start with `imdone ls`
   - Add display flags: `-l` (long), `-t` (time sort), `-r` (reverse)
   - Add filters: `--fav` (favorites), `--limit N`
   - Add format: `--format json|yaml|csv|text`
   - Add custom query: `-q "query"` using imdone filter syntax

3. **Execute the command**: Run using Bash tool

4. **Present results**: Show the output in a readable format

## Examples

**"Show me all issues"**
```bash
imdone ls
```

**"Show me my favorite issues sorted by most recent"**
```bash
imdone ls --fav -t
```

**"List the 5 most recent issues in long format"**
```bash
imdone ls -lt --limit 5
```

**"Show me issues in progress"**
```bash
imdone ls -q 'meta.status="In Progress"'
```

**"Show me enhancement issues that are still open"**
```bash
imdone ls -q 'meta.status="open" and tag:enhancement'
```

**"Export all issues to JSON"**
```bash
imdone ls --format json
```

## Notes

- ★ indicator shows favorited issues in all views
- Default format shows KEY + PATH per line
- `-l` shows detailed table with status, assignee, type
- Queries use imdone filter syntax and are applied locally to synced issues
- Results are filtered to show only issues that exist locally
