quell 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?
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. |
--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, quell prove, the Python SDK and the MCP tools; see how it works.
What does the output look like?
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.
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 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.
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.