---
id: "49498e21-7f1e-4b2b-94fc-dcea7936f786"
name: "How to run bto_jira_audit helper"
micro_summary: "Quick how-to: run the bto_jira_audit() helper from a terminal via stdin; precondition: authenticated Jira tab available."
status: "in_progress"
see_also: []
scope: "Usage examples and preconditions for the `bto_jira_audit()` browser-harness helper defined in agent-workspace/agent_helpers.py. Includes sample invocation, preflight checks, artifact locations, and safety notes."
---
## Preconditions
- An authenticated Chrome tab with `the target Jira host` must be open in the current user profile. The helper will try to find and reuse such a tab automatically (list_tabs() → switch_tab()).
- The call is READ-ONLY. The helper performs only GET/search requests and does not edit issues.

## One-line runnable example (safe, prints paths+counts)

From your shell run:

```bash
browser-harness <<'PY'
import json
print(json.dumps(bto_jira_audit(), indent=2))
PY
```

This runs the helper inside the browser-harness environment, switches to an existing authenticated Jira tab if present, runs the two JQL queries (open/non-Done and completeness), post-filters by assignee.displayName, and writes artifacts to disk.

## Output / artifacts
- Raw JSON (full Jira REST capture): `/Users/jack/.cache/pi-jira-audit/jira_audit_raw_<timestamp>.json`
- Normalized JSON (counts + per-issue flattened): `/Users/jack/.cache/pi-jira-audit/jira_audit_raw_<timestamp>_normalized.json`
- Markdown summary: `/Users/jack/.cache/pi-jira-audit/jira_audit_<timestamp>.md`

## Notes and options
- Optional args (Python kwargs): `out_dir`, `expected_assignee`, `open_jql`, `all_jql`, `fields`, `max_pages`.
- Example: to audit a different assignee (not recommended with current-user JQL), run the helper from Python with `bto_jira_audit(expected_assignee="Alice")` inside stdin (but `assignee = currentUser()` JQL implicitly queries current session user).
- The helper tries to auto-detect and switch to a the target Jira host tab. If no such tab exists, it will still attempt the REST fetches but they may fail if not authenticated; open a Jira tab first to be safe.

## Safety
- This helper is read-only — it uses `/rest/api/3/myself` and `/rest/api/3/search/jql` only.
- Keep the output artifacts private; they contain issue keys, summaries, comments, and user emails.

## Troubleshooting
- If the helper raises a parsing error, rerun with a live Jira tab open and ensure network requests are allowed by the browser session.
- If `openRaw`/`allRaw` counts look off, increase `max_pages` or check whether the Jira site rate-limits the REST requests.