### Manual Pyrefly CI Setup Example

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/installation.mdx

A comprehensive example of a GitHub Actions workflow for manual Pyrefly setup, including dependency installation and type checking.

```yaml
name: Pyrefly Type Check

on:
  pull_request:
    branches: [main]
  workflow_dispatch:  # Allows manual triggering from the GitHub UI

jobs:
  typecheck:
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5

      # Install Python dependencies and create environment
      - name: Install dependencies
        run: |
          python -m venv .venv
          source .venv/bin/activate
          python -m pip install --upgrade pip
          # Install your dependencies; adjust the following lines as needed
          pip install -r requirements-dev.txt

      - name: Install Pyrefly
        run: pip install pyrefly

      - name: Run Pyrefly Type Checker
        run: pyrefly check --output-format=github
```

--------------------------------

### Install Dependencies

Source: https://github.com/facebook/pyrefly/blob/main/lsp/CONTRIBUTING.md

Run this command in the root and client directories to install project dependencies.

```bash
npm install
```

--------------------------------

### Install django-stubs and Virtual Environment

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/django.mdx

Install the django-stubs package and set up a Python virtual environment.

```bash
pip install django-stubs

python3 -m venv .venv
source .venv/bin/activate
```

--------------------------------

### Setup Pyrefly with mason.nvim in Neovim

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/IDE.mdx

Use this configuration to set up Pyrefly via mason.nvim. Ensure mason.nvim and mason-lspconfig.nvim are installed.

```lua
require("mason").setup()
require("mason-lspconfig").setup()
```

--------------------------------

### Install Pyrefly with uv

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/installation.mdx

Installs Pyrefly using uv, initializes the project, and runs a type check with error summarization.

```bash
uvx pyrefly init
uvx pyrefly check --summarize-errors
```

--------------------------------

### SubConfig Example

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/configuration.mdx

Demonstrates how to define multiple SubConfigs with different glob matches and override options. This example shows how to set project-wide errors, then override specific errors and import replacements for different subdirectories and test files.

```toml
replace-imports-with-any = [
  "sympy.*",
  "*.series",
]
ignore-errors-in-generated-code = true

# disable `bad-assignment` and `invalid-argument` for the whole project
[errors]
bad-assignment = false
invalid-argument = false

[[sub-config]]
# apply this to `sub/project/tests/file.py`
matches = "sub/project/tests/file.py"

# any unittest imports will by typed as `typing.Any`
replace-imports-with-any = ["unittest.*"]

[[sub-config]]
# apply this config to all files in `sub/project`
matches = "sub/project/**"

# enable `assert-type` errors in `sub/project`
[sub-config.errors]
assert-type = true

[[sub-config]]
# apply this config to all files in `sub`
matches = "sub/**"

# disable `assert-type` errors in `sub`
[sub-config.errors]
assert-type = false

[[sub-config]]
# apply this config to all files under `tests` dirs in `sub/`
matches = "sub/**/tests/**"

# any pytest imports will be typed as `typing.Any`
replace-imports-with-any = ["pytest.*"]
```

--------------------------------

### Install Type Checkers

Source: https://github.com/facebook/pyrefly/blob/main/scripts/benchmark/README.md

Installs the necessary type checkers for benchmarking. Ensure you are in a virtual environment.

```bash
pip install pyright mypy pyrefly ty zuban
```

--------------------------------

### Install Pyrefly with Pip

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/installation.mdx

Installs Pyrefly using pip, initializes the project, and runs a type check with error summarization.

```bash
pip install pyrefly
pyrefly init
pyrefly check --summarize-errors
```

--------------------------------

### Hello World Example with Pyrefly

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/tensor-shapes-setup.mdx

A minimal Pyrefly example using `from __future__ import annotations` to define a two-layer neural network with typed tensor dimensions. Run `pyrefly check` to verify shapes.

```python
from __future__ import annotations

import torch
import torch.nn as nn
from torch import Tensor
from shape_extensions import Dim


class TwoLayerNet[InDim, HidDim, OutDim](nn.Module):
    def __init__(
        self, 
        in_dim: Dim[InDim],
        hid_dim: Dim[HidDim],
        out_dim: Dim[OutDim],
    ):
        super().__init__()
        self.fc1 = nn.Linear(in_dim, hid_dim)
        self.fc2 = nn.Linear(hid_dim, out_dim)

    def forward[B](self, x: Tensor[B, InDim]) -> Tensor[B, OutDim]:
        h = self.fc1(x)          # pyrefly infers: Tensor[B, HidDim]
        return self.fc2(torch.relu(h))
```

--------------------------------

### Example pyrefly.toml with Custom Settings

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/configuration.mdx

This example demonstrates a custom pyrefly.toml configuration, including specific include/exclude paths, Python environment settings, and per-file/directory error configurations using sub-configs.

```toml
project-includes = ["src"]
project-excludes = ["**/.[!/.]*", "**/tests"]
search-path = ["src"]
site-package-path = ["venv/lib/python3.12/site-packages"]

python-platform = "linux"
python-version = "3.12"
python-interpreter-path = "venv/bin/python3"

replace-imports-with-any = [
  "sympy.*",
  "*.series",
]
ignore-errors-in-generated-code = true

# disable `bad-assignment` and `invalid-argument` for the whole project
[errors]
bad-assignment = false
invalid-argument = false

[[sub-config]]
# apply this to `sub/project/tests/file.py`
matches = "sub/project/tests/file.py"

# any unittest imports will by typed as `typing.Any`
replace-imports-with-any = ["unittest.*"]

[[sub-config]]
# apply this config to all files in `sub/project`
matches = "sub/project/**"

# enable `assert-type` errors in `sub/project`
[sub-config.errors]
assert-type = true

```

--------------------------------

### Package Extension

Source: https://github.com/facebook/pyrefly/blob/main/lsp/CONTRIBUTING.md

Package the extension into a VSIX file for installation. This requires vsce to be installed globally.

```bash
npm install vsce
```

```bash
npm exec vsce package
```

--------------------------------

### Install Pyrefly via mason.nvim in Neovim

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/IDE.mdx

Add 'pyrefly' to the 'ensure_installed' list to automatically install it with mason-lspconfig.nvim.

```lua
require("mason-lspconfig").setup {
  ensure_installed = { "pyrefly" },
}
```

--------------------------------

### Install Mercurial

Source: https://github.com/facebook/pyrefly/blob/main/pyrefly_wasm/README.md

Install the Mercurial version control system using apt. This is a prerequisite for building Pyrefly for WASM.

```bash
sudo apt install mercurial
```

--------------------------------

### Install Dependencies and Run Validation

Source: https://github.com/facebook/pyrefly/blob/main/schemas/CONTRIBUTING.md

Installs necessary Python packages for schema validation and then executes the validation script. Ensure pip is available.

```bash
# Install dependencies (if not already installed)
pip install jsonschema toml

# Run validation
python schemas/validate_schemas.py
```

--------------------------------

### Install Static Docs Dependencies

Source: https://github.com/facebook/pyrefly/blob/main/website/README.md

Use this command to install dependencies for working on the static documentation site only. It does not include WASM dependencies.

```bash
yarn install
```

--------------------------------

### Install Pyrefly with Pixi

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/installation.mdx

Adds Pyrefly using Pixi, initializes the project, and runs a type check with error summarization.

```bash
pixi add pyrefly
pixi run pyrefly init
pixi run pyrefly check --summarize-errors
```

--------------------------------

### Install Dependencies with WASM

Source: https://github.com/facebook/pyrefly/blob/main/website/README.md

Install dependencies for both the static docs site and the Sandbox feature, including WASM dependencies. This command builds the WASM dependencies and then installs the yarn dependencies.

```bash
yarn install-with-wasm-deps
```

--------------------------------

### Run Static Docs Website

Source: https://github.com/facebook/pyrefly/blob/main/website/README.md

Start the development server for the static documentation site. Changes are typically reflected live without a server restart.

```bash
yarn start
```

--------------------------------

### Set up Python virtual environment for runtime tests

Source: https://github.com/facebook/pyrefly/blob/main/TENSOR_SHAPES_CONTRIBUTING.md

Use this to set up a Python 3.12+ virtual environment with torch installed for running runtime tests.

```bash
python3.12 -m venv .tensor-shapes-venv
. .tensor-shapes-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install torch
```

--------------------------------

### Blog Post Metadata Example

Source: https://github.com/facebook/pyrefly/blob/main/website/README.md

Example frontmatter for a blog post written in markdown. This metadata is used by Docusaurus to render the blog post and its associated information.

```markdown
---
title: My Blog # the title of your blog post
description: This is my first blog! # a short description of your blog post
slug: my-first-blog # what you want to url to be
authors: jmarcey # your author name from the authors.yml file, for multiple authors, use a comma separated list [author1, author2]
tags: [hello, python] # a list of tags for your blog post
image: https://i.imgur.com/mErPwqL.png #the image to be used for preview links
hide_table_of_contents: false # set to true to hide the table of contents
---

![image](path/to/image.png) # your blog header image

The first line/paragraph of your blog post

<!-- truncate -->

the rest of your blog post.
```

--------------------------------

### Install clang for macOS

Source: https://github.com/facebook/pyrefly/blob/main/pyrefly_wasm/README.md

Use Homebrew to install clang on macOS if it's not already present. This is a prerequisite for building Pyrefly for WASM.

```bash
brew install llvm
```

--------------------------------

### Install clang for CentOS

Source: https://github.com/facebook/pyrefly/blob/main/pyrefly_wasm/README.md

Install clang on CentOS systems using the dnf package manager. This is a prerequisite for building Pyrefly for WASM.

```bash
sudo dnf install clang
```

--------------------------------

### Install Pyrefly with Poetry

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/installation.mdx

Adds Pyrefly as a development dependency using Poetry, initializes the project, and runs a type check with error summarization.

```bash
poetry add --group dev pyrefly
poetry run pyrefly init
poetry run pyrefly check --summarize-errors
```

--------------------------------

### Buck2 Integration Command Example

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/configuration.mdx

This is the command Pyrefly uses internally for Buck2 integration, demonstrating how optional parameters like isolation-dir and extras are passed.

```sh
buck2 [--isolation-dir <isolation_dir>] bxl --reuse-current-config [<extras>...] prelude//python/sourcedb/pyrefly.bxl:main @<argfile>

```

--------------------------------

### Install Pyrefly Command-Line Tool

Source: https://github.com/facebook/pyrefly/blob/main/README.md

Use pip to install the Pyrefly command-line tool for local Python project analysis.

```bash
pip install pyrefly
```

--------------------------------

### Style Guide Comparison for Module Approaches

Source: https://github.com/facebook/pyrefly/blob/main/tensor-shapes/skills/add-shape-types-to-torch-model/SKILL.md

This section provides a template for comparing your module's approach against the closest matching pattern in the style guide. It helps identify potential improvements and document reasons for not adopting them.

```markdown
## Style guide comparison
| Module | My approach | Closest style guide pattern | Could I improve? |
|--------|------------|---------------------------|-----------------|
| ... | ... | ... | yes/no — reason |
```

--------------------------------

### Python Bindings Example

Source: https://github.com/facebook/pyrefly/blob/main/ARCHITECTURE.md

Shows an example of how Pyrefly might represent Python code as bindings, including definitions, uses, and anonymous statements. It highlights how identifiers are disambiguated using their position.

```python
1: x: int = 4
2: print(x)
```

--------------------------------

### Complete Pyrefly GitHub Actions Workflow Example

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/installation.mdx

A full example of a GitHub Actions workflow that checks Pyrefly types on pull requests to the main branch.

```yaml
name: Pyrefly Type Check

on:
  pull_request:
    branches: [main]

jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: facebook/pyrefly@main
```

--------------------------------

### Configure Pyrefly with pyproject.toml

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/installation.mdx

Example of configuring Pyrefly by adding a [tool.pyrefly] section to your pyproject.toml file to specify search paths.

```toml
[tool.pyrefly]
search_path = [
    "example_directory/..."
]
```

--------------------------------

### Pyrefly Help Command for Subcommands

Source: https://github.com/facebook/pyrefly/blob/main/test/basic.md

Inspect the main help output to understand available subcommands and their aliases. This example shows how `coverage` is listed and `report` is an alias.

```bash
$ $PYREFLY --help | grep -E "^ +(coverage|  report)"
  coverage     Type coverage commands
[0]
```

--------------------------------

### Run Pyrefly Typecheck Benchmark

Source: https://github.com/facebook/pyrefly/blob/main/website/blog/2026-04-10-speed-and-memory-comparison.md

Clone the repository, set up a virtual environment, install type checkers, and run benchmarks for specific packages or all tracked packages.

```bash
git clone https://github.com/facebook/pyrefly.git
cd pyrefly/scripts/benchmark

python -m venv .venv
source .venv/bin/activate
pip install pyright pyrefly ty mypy

python typecheck_benchmark.py --packages 5

python typecheck_benchmark.py --package-names requests flask django

python typecheck_benchmark.py
```

--------------------------------

### Run Website with WASM Rebuild

Source: https://github.com/facebook/pyrefly/blob/main/website/README.md

Start the development server and rebuild the WASM dependencies. Use this command if you need to incorporate WASM changes into the running site.

```bash
yarn start-with-wasm
```

--------------------------------

### Run Tests and Build WASM

Source: https://github.com/facebook/pyrefly/blob/main/website/README.md

Execute snapshot tests powered by Jest. This command first installs dependencies, builds the WASM for testing, and then runs the tests.

```bash
yarn install
scripts/build_wasm_for_test_for_sandcastle.sh
yarn test
```

--------------------------------

### Build and Run Pyrefly

Source: https://github.com/facebook/pyrefly/blob/main/TENSOR_SHAPES_CONTRIBUTING.md

Build the Pyrefly project and then execute the Pyrefly runner script. This validates focused tests, negative expectations, and jaxtyping examples.

```bash
cargo build
python3 tensor-shapes/pyrefly-torch-stubs/run_pyrefly.py
```

--------------------------------

### Override Pyrefly LSP Config in Neovim

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/IDE.mdx

Use this to override specific settings like the command to run or filetypes supported. This example shows how to run Pyrefly installed via `uv` without adding it to your PATH.

```lua
vim.lsp.config('pyrefly', {
    -- example of how to run `uv` installed Pyrefly without adding to your path
    cmd = { 'uvx', 'pyrefly', 'lsp' }
})
```

--------------------------------

### Fallback Search Path Example

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/import-resolution.mdx

Illustrates the fallback search path for a file within a nested directory structure. This path is automatically constructed when no config file is present.

```text
/
 |- projects/
    |- project_a/
    |  |- b/
    |  |  |- c.py
    |  |- d.py
    |- project_e/
       |- f.py
```

--------------------------------

### Import and Instantiate Class

Source: https://github.com/facebook/pyrefly/blob/main/pyrefly/test_laziness/test_import_class_instantiated.md

Demonstrates importing a class 'Foo' from module 'b' and creating an instance of it.

```python
from b import Foo
f = Foo()
```

--------------------------------

### Install Pyrefly v1.1

Source: https://github.com/facebook/pyrefly/blob/main/website/blog/2026-06-17-v1.1.md

Use this command to upgrade to the latest version of Pyrefly. Ensure you have pip installed.

```shell
pip install --upgrade pyrefly==1.1.0
```

--------------------------------

### Dump Configuration

Source: https://github.com/facebook/pyrefly/blob/main/test/config.md

This snippet shows how to use the `dump-config` command to display the project's configuration, including covered files and resolved import paths. It sets up a sample project structure and then runs the command.

```scrut
$ touch $TMPDIR/foo.py && mkdir $TMPDIR/bar && touch $TMPDIR/bar/baz.py && touch $TMPDIR/bar/qux.py && mkdir $TMPDIR/spp && touch $TMPDIR/spp/mylib.py \
> && $PYREFLY dump-config --site-package-path $TMPDIR/spp/ $TMPDIR/foo.py $TMPDIR/bar/*.py
Default configuration
  Using interpreter: * (glob)
  Covered files:
    */bar/baz.py (glob)
    */bar/qux.py (glob)
  Resolving imports from:
    Fallback search path (guessed from importing file with heuristics): * (glob)
    Site package path from user: * (glob)
    Site package path queried from interpreter: * (glob)
Default configuration
  Using interpreter: * (glob)
  Covered files:
    */foo.py (glob)
  Resolving imports from:
    Fallback search path (guessed from importing file with heuristics): * (glob)
    Site package path from user: * (glob)
    Site package path queried from interpreter: * (glob)
[0]
```

--------------------------------

### Initialize Pyrefly for Migration

Source: https://github.com/facebook/pyrefly/blob/main/README.md

Run 'pyrefly init' to begin migrating your project from Mypy or Pyright to Pyrefly.

```bash
pyrefly init
```

--------------------------------

### Run LSP Go to Definition Benchmark (Single-repo)

Source: https://github.com/facebook/pyrefly/blob/main/scripts/benchmark/README.md

Benchmarks LSP 'Go to Definition' latency for a specific repository. This mode requires the repository to be already cloned and allows specifying custom server commands.

```bash
python3 lsp_benchmark.py \
    --root ~/projects/some-python-repo \
    --servers pyrefly \
    --pyrefly-cmd "pyrefly lsp" \
    --runs 20 \
    --json results.json
```

```bash
python3 lsp_benchmark.py \
    --root ~/projects/some-python-repo \
    --pyrefly-cmd "pyrefly lsp" \
    --seed 42 --runs 50
```

```bash
python3 lsp_benchmark.py \
    --root ~/projects/some-python-repo \
    --pyrefly-cmd "pyrefly lsp" \
    --ty-cmd "ty server" \
    --pyright-cmd "pyright-langserver --stdio" \
    --zuban-cmd "zubanls" \
    --runs 20
```

--------------------------------

### Run Full Test Suite with Buck Mode

Source: https://github.com/facebook/pyrefly/blob/main/AGENTS.md

Execute the full test suite, explicitly setting the build mode to buck.

```bash
./test.py --mode buck
```

--------------------------------

### Install Pyrefly with Conda

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/installation.mdx

Installs Pyrefly using Conda from the conda-forge channel, initializes the project, and runs a type check with error summarization.

```bash
conda install -c conda-forge pyrefly
pyrefly init
pyrefly check --summarize-errors
```

--------------------------------

### Run LSP Go to Definition Benchmark (Multi-package)

Source: https://github.com/facebook/pyrefly/blob/main/scripts/benchmark/README.md

Benchmarks LSP 'Go to Definition' latency across servers using multi-package mode. This mode auto-clones packages from a specified JSON file.

```bash
python3 lsp_benchmark.py --install-envs install_envs.json
```

```bash
python3 lsp_benchmark.py --install-envs install_envs.json -c pyrefly -p 3 -r 10
```

```bash
python3 lsp_benchmark.py --install-envs install_envs.json -n requests flask django -r 20
```

```bash
python3 lsp_benchmark.py --install-envs install_envs.json -o ./my_results --os-name macos
```

--------------------------------

### Pytest Fixture Navigation Example

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/pytest.mdx

Illustrates how Pyrefly understands fixture-by-name conventions for navigation. Go-to-definition on the parameter jumps to the fixture definition, and find-references on the fixture name includes requesting parameters.

```python
import pytest

@pytest.fixture
def database_url() -> str:
    return "sqlite://"

def test_connection(database_url):
    assert database_url.startswith("sqlite")
```

--------------------------------

### Minimal Typed Function Example

Source: https://github.com/facebook/pyrefly/blob/main/website/blog/2026-04-01-100-percent-type-coverage.md

An example of a function that remains after Pyrefly Prune™ has removed all untyped code. This function is fully typed and represents the minimal, verifiable code left.

```python
def model(x: float) -> float:
   return x
```

--------------------------------

### Preventing Override of typing_extensions with Installed Packages

Source: https://github.com/facebook/pyrefly/blob/main/test/args.md

Shows how Pyre-check prioritizes typeshed over installed packages to prevent accidental overrides of `typing_extensions`. This ensures that the standard library's type stubs are used when available.

```bash
$ mkdir $TMPDIR/site_package_path && \
> echo "x: int = 42" > $TMPDIR/site_package_path/typing_extensions.py && \
> echo "from typing import TypedDict; from typing_extensions import NotRequired; class C(TypedDict): x: NotRequired[int]" > $TMPDIR/site_package_path/lib.py && \
> echo "from lib import C; C()" > $TMPDIR/foo.py && \
> $PYREFLY check $TMPDIR/foo.py --site-package-path $TMPDIR/site_package_path
[0]
```

--------------------------------

### Typed Interface Receipt Example

Source: https://github.com/facebook/pyrefly/blob/main/tensor-shapes/skills/add-shape-types-to-torch-model/SKILL.md

This is an example of the typed interface receipt format used to document shape tracking status within a PyTorch model's ClassName.forward method. It details the outcome of various restructuring checks.

```text
## Typed interface receipt [<Module>.<var>]: <variable> in <ClassName.forward>
- int()/round() cast: [removed / not applicable — reason]
- Sequential(*list): [restructured / not applicable — reason]
- list→tuple: [not applicable — reason]
- Branch join: [not applicable — reason]
- Inlined expressions: [split / not applicable — reason]
- Missing stub/DSL: [checked stubs + `@uses_shape_dsl` IR — reason]
- Dim | None reclassification: [reclassified param X / not applicable — reason]
- Bridge dim: [promoted X to class Dim / not applicable — reason]
- Config parameterization: [parameterized Config[...] / not applicable — reason]
Result: still bare after all checks. Using typed interface because ___. 
```

--------------------------------

### Pyrefly Bundled Stub Resolution Logic

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/import-resolution.mdx

This decision tree outlines when Pyrefly uses bundled third-party stubs versus installed stubs or reports errors. It depends on the presence of a Pyrefly config file and whether the package is installed.

```text
- Pyrefly config file present?
   - Yes
      - Is the package installed?
         - Yes
            - Are stubs installed by user?
               - Yes
                  Installed stubs are used.
               - No
                  UntypedImport error.
         - No
            MissingImport error.
   - No
      - Is the package installed?
         - Yes
            Bundled stubs used.
         - No
            MissingSourceForStubs error.
```

--------------------------------

### Snippet with Config File

Source: https://github.com/facebook/pyrefly/blob/main/test/snippet.md

Demonstrates using a specific configuration file for the snippet command via the `--config` flag.

```scrut
$ echo "python_version = \"3.11\"" > pyrefly.toml && $PYREFLY snippet "x: int = 42" --config pyrefly.toml
 INFO 0 errors
[0]
```

--------------------------------

### Define Named Tuple and Enum

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/error-kinds.mdx

Example of defining a named tuple and an enum. Ensure imports are present.

```python
from collections import namedtuple
from enum import Enum

RepoDetails = namedtuple("repo_details", ["source_dir", "age"])
DviState = Enum("_dvistate", "pre outer inpage")
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/facebook/pyrefly/blob/main/AGENTS.md

Execute linters and tests using the test.py script. This is a heavyweight operation.

```bash
./test.py
```

--------------------------------

### Run Pyrefly runtime tests

Source: https://github.com/facebook/pyrefly/blob/main/TENSOR_SHAPES_CONTRIBUTING.md

Execute all runtime tests for Pyrefly's tensor-shape stubs and runnable example models.

```bash
python tensor-shapes/pyrefly-torch-stubs/run_runtime_tests.py
```

--------------------------------

### Create Pyrefly Config in Empty Directory

Source: https://github.com/facebook/pyrefly/blob/main/test/init.md

Use `pyrefly init --non-interactive` to create a new pyrefly.toml configuration file in an empty directory. This command is suitable for automated setups where user interaction is not possible.

```bash
$ mkdir $TMPDIR/init_test && \
> $PYREFLY init --non-interactive $TMPDIR/init_test
 INFO New config written to `*/pyrefly.toml` (glob)
* (glob*)
[0]
```

--------------------------------

### Run Pyrefly on specific files

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/migrating-from-pyright.mdx

Use this command to check specific Python files with Pyrefly. No configuration is needed to start.

```sh
$ pyrefly check file1.py file2.py
```

--------------------------------

### Run Pyrefly on all project files

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/migrating-from-mypy.mdx

Navigate to the project root and run Pyrefly to check all files within the project.

```sh
cd your/project
pyrefly check
```

--------------------------------

### Python Redefinition of Annotated Variable

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/error-kinds.mdx

Shows an example where a variable is annotated again with a different type within the same scope, triggering a redefinition error.

```python
def f(x: int) -> None:
    x: str = str(x)  # redefinition
```

--------------------------------

### Custom Build System Query Output Format

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/configuration.mdx

The command executed for custom build systems must output a JSON file describing the repository root and a database of targets. This includes source files, dependencies, build file paths, and Python interpreter details for each target.

```json
{
    "root": "/path/to/this/repository",
    "db": {
        "//colorama:py-stubs": {
            "srcs": {
                "colorama": [
                    "colorama/__init__.pyi"
                ]
            },
            "deps": [],
            "buildfile_path": "colorama/BUCK",
            "python_version": "3.12",
            "python_platform": "linux"
        },
        "//colorama:py": {
            "srcs": {
                "colorama": [
                    "colorama/__init__.py"
                ]
            },
            "deps": ["//colorama:py-stubs"],
            "buildfile_path": "colorama/BUCK",
            "python_version": "3.12",
            "python_platform": "linux"
        },
        "//colorama:colorama": {
            "alias": "//colorama:py"
        }
    }
}

```

--------------------------------

### Invalid Literal Usage

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/error-kinds.mdx

Shows legal and illegal uses of `typing.Literal`. The illegal example uses an instance of a custom class as a parameter.

```python
from typing import Literal

# These are legal
Literal[1]
Literal['a', 'b', 'c']
# This is not
class A:
  ...
Literal[A()]
```

--------------------------------

### Fallback Search Path for c.py

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/import-resolution.mdx

Demonstrates the fallback search path for 'c.py' and how it can be imported. This path includes directories from the file's location up to the filesystem root.

```text
c.py's fallback search path would be ['/projects/project_a/b', '/projects/project_a', '/projects', '/']
- d.py could be importable with the paths d, project_a.d, or projects.project_a.d.
- f.py could be importable with the paths project_e.f or projects.project_e.f.
```

--------------------------------

### Importing from stub files

Source: https://github.com/facebook/pyrefly/blob/main/test/find.md

Pyrefly can resolve imports from stub files (.pyi). This example demonstrates setting up a stub file and importing from it.

```bash
$ mkdir $TMPDIR/test-stubs && touch $TMPDIR/test-stubs/utils.pyi && touch $TMPDIR/test-stubs/main.pyi && \
> echo "x: int = 1" > $TMPDIR/test-stubs/utils.pyi && \
> echo "from test.utils import x" > $TMPDIR/test-stubs/main.pyi && \
> $PYREFLY check --python-version 3.13.0 "$TMPDIR/test-stubs/main.pyi"
[0]
```

--------------------------------

### Run Primer Pipeline Locally

Source: https://github.com/facebook/pyrefly/blob/main/scripts/issue_ranker/AGENTS.md

Execute the primer pipeline locally to generate primer data. Requires the pyrefly binary. Use --pyrefly if cargo is not available.

```bash
python3 scripts/compare_typecheckers.py --output /tmp/primer.json \
  --pyrefly /path/to/pyrefly
```

--------------------------------

### Find First Pyrefly Config

Source: https://github.com/facebook/pyrefly/blob/main/test/config.md

Demonstrates how Pyrefly finds the first available configuration file, prioritizing `pyproject.toml`.

```scrut
$ echo "[tool.pyrefly]" > $TMPDIR/config_finder/project/pyproject.toml && \
> $PYREFLY dump-config $TMPDIR/config_finder/project/main.py
Configuration at `*/config_finder/project/pyproject.toml` (glob)
* (glob+)
[0]
```

--------------------------------

### Simple Class Hierarchy Example

Source: https://github.com/facebook/pyrefly/blob/main/website/blog/2026-03-18-lessons-from-pyre.md

A basic Python class hierarchy used to illustrate cyclic data dependencies in type checking.

```Python
class A: ...
class B(A): ...
class C(B): ...
```

--------------------------------

### Default Ignore Behavior

Source: https://github.com/facebook/pyrefly/blob/main/test/ignores.md

By default, Pyrefly enables `# type: ignore` and `# pyrefly: ignore` comments. This example shows the output when these are active.

```bash
$ mkdir $TMPDIR/enabled_ignores && \
> touch $TMPDIR/enabled_ignores/pyrefly.toml && \
> echo -e "1 + '1' # type: ignore\n1 + '1' # pyrefly: ignore\n1 + '1' # pyright: ignore" > $TMPDIR/enabled_ignores/foo.py && \
> $PYREFLY check $TMPDIR/enabled_ignores/foo.py --output-format=min-text
ERROR */foo.py:3* (glob)
[1]
```

--------------------------------

### Snippet with JSON Output Format

Source: https://github.com/facebook/pyrefly/blob/main/test/snippet.md

Shows how to get snippet analysis results in JSON format using the `--output-format=json` flag.

```scrut
$ $PYREFLY snippet "x: int = 'hello'" --output-format=json
{
  "errors": [
    {
      "line": 1,
      "column": 10,
      "stop_line": 1,
      "stop_column": 17,
      "path": "snippet",
      "code": -2,
      "name": "bad-assignment",
      "description": "`Literal['hello']` is not assignable to `int`",
      "concise_description": "`Literal['hello']` is not assignable to `int`",
      "severity": "error"
    }
  ]
} (no-eol)
[1]
```

--------------------------------

### Build with Debug Profile for Full Debug Info

Source: https://github.com/facebook/pyrefly/blob/main/CONTRIBUTING.md

When needing to step through code with a debugger, build the project using the `dbg` profile to include full debug information. This is necessary for effective debugging with tools like lldb or graphical debuggers.

```bash
cargo build --profile dbg
```

--------------------------------

### Upgrade Pyrefly to v1.1.1

Source: https://github.com/facebook/pyrefly/blob/main/release_notes/release-notes-v1.1.1.md

Use this command to upgrade your Pyrefly installation to the latest patch version. Ensure you are using pip for package management.

```bash
pip install --upgrade pyrefly==1.1.1
```

--------------------------------

### Run verify_port.sh Script

Source: https://github.com/facebook/pyrefly/blob/main/tensor-shapes/skills/add-shape-types-to-torch-model/SKILL.md

Execute the `verify_port.sh` script on your port file to perform heuristic quality checks. Paste the full output for review.

```bash
tensor-shapes/skills/add-shape-types-to-torch-model/verify_port.sh <path/to/your/port.py>
```

--------------------------------

### Configure Strict Override Enforcement

Source: https://github.com/facebook/pyrefly/blob/main/website/docs/error-kinds.mdx

Example TOML configuration to set the severity of the `missing-override-decorator` error to `error`, enabling strict override enforcement.

```toml
[tool.pyrefly]
errors = { missing-override-decorator = "error" }
```

--------------------------------

### Module a.py: Imports and uses a function

Source: https://github.com/facebook/pyrefly/blob/main/pyrefly/test_laziness/test_bare_import_forces_exports.md

This file imports the `light` function from module `b` and then calls it. It serves as the entry point for the test case.

```python
from b import light
x = light()
```