# quell find

> The primary quell command. Reads guard clauses, reports which have no test, and with --fix writes verified pytest tests. Options, output and exit codes.

Canonical page: https://quelltest.com/docs/cli/find

`quell find` scans Python code for guard clauses that no test covers and, with `--fix`, generates, verifies and writes pytest tests for the ones it can prove. Use it as your first command on a Python project and again after changing validation logic. It is rule-based: no LLM, no network and no code leaves your machine unless you pass `--use-llm`.

## What is the syntax?

```bash
quell find [TARGET]                 # report gaps, write nothing but quell-report.json
quell find [TARGET] --fix           # also write tests for verified cases
quell find [TARGET] --fix --use-llm # let an LLM try the cases the rules cannot handle
quell find [TARGET] --format github # emit GitHub Actions annotations
```

`TARGET` is a file or directory and defaults to `.`. In a directory, `*.py` files are scanned except files with `test` in their name, `.venv`, `site-packages` and `__pycache__`.

## What are the options?

| Option | Meaning |
| --- | --- |
| `--fix` | Generate tests and, after verification and confirmation, write them. |
| `--auto` | Listed as "Skip confirmation prompts (for CI)". In the 2.0.1 repository build tested for these docs it was not passed through by `quell find`, so `--fix` still prompts per test. |
| `--use-llm` | Enable the LLM fallback for guard types the rule engine cannot handle. Requires `quell auth`. |
| `--sync` | Push a privacy-safe report to the cloud after the scan (Pro and Team only). See [Connector](https://quelltest.com/docs/connector.md). |
| `--root PATH` | Project root (default `.`): where tests are searched, config is read and `quell-report.json` is written. |
| `--format`, `-f` | `console` (default) or `github`. |

## What does it read?

Guard clauses, using Python's `ast` module: `if cond: raise`, `if x is None: raise/return`, `if x not in COLLECTION: raise`, `assert`, `isinstance` checks, authentication and permission checks, `try/except` re-raises, a function body that always raises, bare `except`, silent `return None`, and magic values in conditions. Docstrings and Pydantic models are read by [`quell ci`](https://quelltest.com/docs/cli/ci.md), `quell prove`, the Python SDK and the MCP tools; see [how it works](https://quelltest.com/docs/how-it-works.md).

## What does the output look like?

```text
                 Logic Gaps Found (2 untested / 2 total)
┌─────────────┬──────────┬──────────────────────────┬──────────┬────────┐
│ File        │ Function │ Guard Clause             │ Type     │ Method │
├─────────────┼──────────┼──────────────────────────┼──────────┼────────┤
│ payments.py │ charge   │ if amount <= 0:          │ boundary │        │
│ payments.py │ discount │ if pct < 0 or pct > 100: │ boundary │        │
└─────────────┴──────────┴──────────────────────────┴──────────┴────────┘
```

With `--fix`, each gap is generated, verified and shown, and you are asked `Write this test? [Y/n]`. Candidates that fail verification are reported with a reason such as `test passes even when the guard is violated` or the first line of the pytest failure. Gaps with no deterministic rule get a stub in `tests/scaffold/` (the `scaffold_dir` setting).

The end of the run prints the three-bucket summary and the score, and the full detail is written to `quell-report.json` in the project root. See [three-bucket output](https://quelltest.com/docs/reference/buckets.md).

## What does `--format github` do?

It prints one `::warning file=...,line=...,title=...` workflow command per untested guard, which GitHub Actions turns into inline pull-request annotations, and `::notice::` when everything is covered. [`quell install --pr`](https://quelltest.com/docs/cli/install.md) writes a workflow that uses it.

## What are the exit codes?

`quell find` exits 0 whether or not gaps were found. To fail a build on a low score use [`quell ci`](https://quelltest.com/docs/cli/ci.md).

## Does it have deprecated aliases?

`quell scan` and `quell check` are older entry points that print a deprecation notice and will be removed in v2.2.

Looking for the JavaScript or TypeScript scanner? See [npm CLI reference](https://quelltest.com/docs/npm/cli.md).
