mirror-cli 0.1.2
Python CLI for interacting with the January Mirror API.
Requires Python: >=3.10

# Mirror CLI

Python CLI to interact with the January Mirror API. An API key is required.

## Install

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install .
```

Python 3.10+ is required. The only runtime dependency is `requests`.

## Configure

- `MIRROR_API_KEY` — your API key. You get this from the January team.
- `MIRROR_BASE_URL` — (optional) the base URL for the Mirror API. 

## Usage

Run via `mirror-cli ...` or `python -m mirror_cli ...` from this folder.

### Active patient state
Most commands need a `--patient-id`. To save typing, the CLI caches the last created patient as the "active patient" in your local config (`~/.config/mirror-cli/context.json`). If you omit `--patient-id`, commands will use this active patient. You can set or change it explicitly with `mirror-cli use-patient --patient-id ...`, view it with `mirror-cli active-patient`, or clear it with `mirror-cli clear-active-patient`. Passing `--patient-id` always overrides the active value.

```bash
mirror-cli create-patient --first-name Jane --last-name Doe --gender female --birthdate 1990-01-01
mirror-cli list-patients --limit 20
mirror-cli upload-document --file ./sample_data/sample_labcorp.pdf
mirror-cli list-documents
mirror-cli get-report --include-content --poll-interval 5 --max-wait 3600

mirror-cli use-patient --patient-id pat_123        # set active patient
mirror-cli active-patient                           # show active patient
mirror-cli clear-active-patient                     # clear active patient
```

Global flags: `--base-url`, `--api-key`, `--timeout`, `--json`, `--verbose`.


## Notes

- Document upload uses the two-step intent + presigned POST flow from the provided Postman collection.
- Report retrieval starts the job and polls until completion (or until `--max-wait` elapses).

## Typical flow

1) Create a patient:
```bash
mirror-cli create-patient --first-name Jane --last-name Doe --gender female --birthdate 1990-01-01
```

2) Upload a document (intent + presigned upload happen automatically):
```bash
mirror-cli upload-document --patient-id pat_123 --file ./lab.pdf
```

3) Verify the upload:
```bash
mirror-cli list-documents --patient-id pat_123
```

4) Request a report (starts the job and polls until done):
```bash
mirror-cli get-report --patient-id pat_123 --include-content --poll-interval 5 --max-wait 180
```
When completed, the CLI prints `Report URL: <presigned link>`; use `--json` to see the full payload. Flags `--job-id`, `--force-context`, and `--force-report` are available when you need more control.

Active patient helper:
- After `create-patient`, the returned ID is saved as the active patient.
- Commands that take `--patient-id` will default to the active patient if you omit the flag; you can always override by passing `--patient-id` explicitly.
- Manage it explicitly with `mirror-cli use-patient --patient-id ...`, `mirror-cli active-patient`, and `mirror-cli clear-active-patient`.

## Publish (manual)

1) Bump the version in `pyproject.toml`.
2) Build from the `mirror-cli/` folder:
   ```bash
   python -m pip install --upgrade build twine
   python -m build
   ```
3) Upload with Twine (PyPI): 
   ```bash
   export PYPI_TOKEN="pypi-********"
   python -m twine upload dist/* -u __token__ -p "$PYPI_TOKEN"
   ```
   For TestPyPI, add `--repository testpypi`.
   Note: Token is saved in 1Password with the main account credentials.
4) Verify:
   ```bash
   pip install --upgrade mirror-cli
   mirror-cli --version
   ```