> ## Documentation Index
> Fetch the complete documentation index at: https://docs.okrapdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filter Jobs with --jq

> Use jq expressions to filter, transform, and pipe CLI output

## Overview

Every `okra` command that outputs JSON supports the `--jq` flag for inline filtering. This mirrors the `gh` CLI pattern — no separate `| jq` pipe needed.

`--jq` implies `--json` automatically.

## Filter completed jobs

```bash theme={null}
okra jobs list --jq '[.[] | select(.status=="completed")] | .[0:5]'
```

Output:

```json theme={null}
[
  { "job_id": "ocr-F84H8rAjY...", "status": "completed", "filename": "Q3-2024.pdf" },
  { "job_id": "ocr-qKLuQqM8T...", "status": "completed", "filename": "Annual-Report.pdf" }
]
```

## Extract just job IDs

```bash theme={null}
okra jobs list --jq '[.[] | select(.status=="completed")] | map(.job_id)'
```

```json theme={null}
["ocr-F84H8rAjY...", "ocr-qKLuQqM8T...", "ocr-gaSpuGK3P..."]
```

## Comma-separated IDs (for piping into `okra task`)

```bash theme={null}
okra jobs list --jq '[.[] | select(.status=="completed")] | .[0:3] | map(.job_id) | join(",")'
```

```
"ocr-F84H8rAjY...,ocr-qKLuQqM8T...,ocr-gaSpuGK3P..."
```

## One-liner: pipe 3 completed jobs into a multi-doc task

```bash theme={null}
okra task $(okra jobs list --jq '[.[] | select(.status=="completed")] | .[0:3] | map(.job_id) | join(",")' | tr -d '"') \
  -m "compare revenue across these documents"
```

This:

1. Lists all jobs as JSON
2. Filters to completed only
3. Takes the first 3
4. Joins their IDs with commas
5. Passes the result as the document list to `okra task`

## Filter by filename pattern

```bash theme={null}
# Only annual reports
okra jobs list --jq '[.[] | select(.filename | test("annual"; "i"))]'

# Only PDFs from 2024
okra jobs list --jq '[.[] | select(.filename | test("2024"))]'
```

## Sort by page count

```bash theme={null}
okra jobs list --jq 'sort_by(.total_pages) | reverse | .[0:5] | map({filename, total_pages})'
```

## Count jobs by status

```bash theme={null}
okra jobs list --jq 'group_by(.status) | map({status: .[0].status, count: length})'
```

```json theme={null}
[
  { "status": "completed", "count": 42 },
  { "status": "processing", "count": 3 },
  { "status": "failed", "count": 1 }
]
```

## Combine with other commands

```bash theme={null}
# Get results for the most recent completed job
JOB=$(okra jobs list --jq '[.[] | select(.status=="completed")][0].job_id' | tr -d '"')
okra jobs results "$JOB" -o markdown

# Export tables from all completed jobs to CSV directories
for id in $(okra jobs list --jq '[.[] | select(.status=="completed")] | .[].job_id' | tr -d '"[],' | tr ' ' '\n'); do
  okra elements export "$id" -t tables -f csv -d "exports/${id}" -o json >/dev/null
done
```

## Bulk cancel last N jobs

```bash theme={null}
# Cancel the last 4 jobs
okra jobs list --jq '.[-4:].[].job_id' | tr -d '"' | xargs -I{} okra jobs cancel {}
```

## Reference

The `--jq` flag is available on any command that supports `--json` output. It uses your system's `jq` binary, so any valid jq expression works.

```bash theme={null}
# These are equivalent:
okra jobs list --json | jq '.[0:3]'
okra jobs list --jq '.[0:3]'
```