Jira Attachment Cleaner

Python CLI that inventories Jira issues for large/old attachments, lets you mark them for removal, and then deletes them while tracking progress (TODO → IN_PROGRESS → DONE/ERROR). If an attachment cannot be deleted because Jira reports it still has related comments, the tool removes any comments that reference the attachment and tries again.

Requirements

• Python 3.9+
• Jira Cloud (or Server/DC with the v3 REST API)
• A Jira API token with permission to read/delete attachments and delete comments

Install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

Copy config.example.json to config.json and fill in your Jira details:

{
  "base_url": "https://your-domain.atlassian.net",
  "email": "you@example.com",
  "api_token": "atlassian_api_token",
  "project_keys": ["OPS", "PLAT"],
  "verify_ssl": true,
  "page_size": 50
}

• project_keys: default project scope. Override with --projects when needed. You can leave the list empty if you primarily use the interactive picker— it will fetch available projects directly from Jira.
• page_size: batch size when paging through Jira search results.
• Store the file securely; it contains secrets.

State is stored in state/state.json (configurable via --state-file). The CLI creates the folder automatically.

Commands

Each command accepts --config to point at a specific config file.

1. List candidate attachments

jira-utils list --before 2023-01-01 --min-size-mb 5

Outputs a table with project, issue key, attachment name/id, size, creation date, and whether it is already tracked in the state file. Filtering options:

• --projects OPS PLAT
• --issue-types Story Task
• --min-size-mb 10
• --before 2022-12-31 (required)
• --max-issues 100 (useful while testing)
• --verbose prints why attachments are skipped (date/size) so you can tune filters.

2. Mark attachments for deletion

Re-run the same filters, optionally narrowing to explicit attachment IDs you copied from the list output:

# Mark every attachment that matches the filters
jira-utils mark --before 2023-01-01 --min-size-mb 5

# Mark individual attachments
jira-utils mark --before 2023-01-01 --min-size-mb 5 \
  --attachment-id 12345 --attachment-id 67890

Marked attachments are saved with status TODO inside the state file.

3. Process (delete) queued attachments

jira-utils process               # only TODO items
jira-utils process --retry-errors  # include previous failures
jira-utils process --limit 5

For each attachment, the CLI:

1. Updates status to IN_PROGRESS.
2. Calls the Jira delete attachment API.
3. On specific failure codes, scans issue comments for references to the attachment (id, filename, or wiki-style [^name] markers), deletes those comments, and retries deletion.
4. Marks the attachment DONE or ERROR (with the error text).

4. Show current state

jira-utils status

Displays every tracked attachment with status and last error (if any).

5. Interactive picker

Launch an ncurses UI to review attachments, select the ones you want to delete, and watch their status change (TODO → IN_PROGRESS → DONE/ERROR) as the tool processes them sequentially:

jira-utils interactive --before 2023-01-01 --min-size-mb 5

Filter overview:

• Interactive mode now opens on a unified filter screen. Press Enter to load attachments, p to adjust projects, t to pick issue types (Story, Task, Bug, etc.), m to edit the minimum attachment size, and b to change the date cutoff (before).
• Leaving either the project or issue-type selection empty includes everything you can access, which is handy when you want to review all projects or all issue types at once.

Project / issue-type pickers:

• Use Space to toggle an item, a to select/deselect all, c to clear, m to tweak the minimum size, b to edit the date, and Enter to return to the filter overview.

Attachment list controls:

• Arrow keys (or j / k) move the cursor; hold Shift with the arrows for range selects.
• Space toggles the current row. a selects/clears all. c clears the current selection.
• Press m to adjust the minimum size threshold or b to change the cutoff date; if deletions are running the reload happens once processing ends.
• Press d (or Enter) to delete the selected attachments. Processing happens in the background, so you can keep scrolling while items are deleted and watch statuses update in real time. Attachments already marked as DONE are skipped automatically.
• Use p to jump straight to the project picker, t for the issue-type picker, or f to revisit the filter overview without exiting the app. q (or Esc) still exits (double-press while deletions are running).

The interactive mode requires curses, which ships with macOS/Linux Python builds. On Windows, use WSL or another environment that provides curses.

Notes & Tips

• Use narrow filters when testing to avoid hitting Jira rate limits.
• Comment cleanup is aggressive: any issue comment containing the attachment name/ID is removed. Review filters before running process in production scenarios.
• The CLI purposefully deletes attachments sequentially so progress is easy to follow and rollback is simple.
• If you need different retention policies per project, run list/mark/process per project with project-specific arguments.
• For end-to-end debugging, opt into the live pytest by setting JIRA_LIVE_CONFIG (and optionally JIRA_LIVE_PROJECTS, JIRA_LIVE_BEFORE, JIRA_LIVE_MIN_SIZE_MB) before running pytest tests/test_live_search.py -k live -s. The test will call Jira, list the first few attachments it sees, and fail if no candidates are found.