diff --git a/src/api/json/catalog.json b/src/api/json/catalog.json
index 561d676306a..4dc6ff8ac87 100644
--- a/src/api/json/catalog.json
+++ b/src/api/json/catalog.json
@@ -4747,6 +4747,18 @@
       "fileMatch": ["pyproject.toml"],
       "url": "https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/pyproject.json"
     },
+    {
+      "name": "pyrefly.toml",
+      "description": "Pyrefly configuration file",
+      "fileMatch": ["pyrefly.toml"],
+      "url": "https://json.schemastore.org/pyrefly.json"
+    },
+    {
+      "name": "Pyrefly tool configuration",
+      "description": "Pyrefly configuration in pyproject.toml",
+      "fileMatch": ["pyproject.toml"],
+      "url": "https://json.schemastore.org/pyrefly-tool.json"
+    },
     {
       "name": "Pyright",
       "description": "Pyright Configuration",
diff --git a/src/schemas/json/pyrefly-tool.json b/src/schemas/json/pyrefly-tool.json
new file mode 100644
index 00000000000..26588426a90
--- /dev/null
+++ b/src/schemas/json/pyrefly-tool.json
@@ -0,0 +1,140 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Pyrefly Tool Configuration",
+  "description": "Schema for tool.pyrefly section in pyproject.toml",
+  "type": "object",
+  "properties": {
+    "project-includes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Files to include as sources (user-space code)",
+      "default": ["**/*"]
+    },
+    "project-excludes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Files to exclude from sources",
+      "default": ["**/*venv/**"]
+    },
+    "search-path": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of directories where imports are resolved from"
+    },
+    "typeshed-path": {
+      "type": "string",
+      "description": "Override bundled typeshed with custom path"
+    },
+    "python-interpreter": {
+      "type": "string",
+      "description": "Path to Python executable for environment querying"
+    },
+    "python-platform": {
+      "type": "string",
+      "description": "Platform for sys.platform checks",
+      "enum": ["darwin", "linux", "win32"]
+    },
+    "python-version": {
+      "type": "string",
+      "description": "Python version string",
+      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
+    },
+    "site-package-path": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of directories containing third-party packages"
+    },
+    "conda-environment": {
+      "type": "string",
+      "description": "Name of conda environment to use"
+    },
+    "untyped-def-behavior": {
+      "type": "string",
+      "description": "How to handle untyped function definitions",
+      "enum": [
+        "check-and-infer-return-type",
+        "check-and-infer-return-any",
+        "skip-and-infer-return-any"
+      ],
+      "default": "check-and-infer-return-type"
+    },
+    "replace-imports-with-any": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Module patterns to replace with typing.Any"
+    },
+    "ignore-errors-in-generated-code": {
+      "type": "boolean",
+      "description": "Ignore errors in generated code (marked with @generated)",
+      "default": false
+    },
+    "use-untyped-imports": {
+      "type": "boolean",
+      "description": "Skip py.typed checks for site-package imports",
+      "default": true
+    },
+    "ignore-missing-source": {
+      "type": "boolean",
+      "description": "Skip checks for missing non-stub packages",
+      "default": true
+    },
+    "permissive-ignores": {
+      "type": "boolean",
+      "description": "Consider any ignore comment to suppress errors",
+      "default": false
+    },
+    "errors": {
+      "type": "object",
+      "description": "Enable/disable specific error types",
+      "properties": {
+        "assert-type": { "type": "boolean" },
+        "bad-argument-count": { "type": "boolean" },
+        "bad-argument-type": { "type": "boolean" },
+        "bad-assignment": { "type": "boolean" },
+        "bad-return": { "type": "boolean" },
+        "invalid-inheritance": { "type": "boolean" },
+        "missing-return": { "type": "boolean" },
+        "undefined-import": { "type": "boolean" },
+        "undefined-variable": { "type": "boolean" },
+        "unused-import": { "type": "boolean" },
+        "unused-variable": { "type": "boolean" }
+      },
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "sub-config": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "matches": {
+            "type": "string",
+            "description": "File pattern to match"
+          },
+          "untyped-def-behavior": {
+            "type": "string",
+            "enum": [
+              "check-and-infer-return-type",
+              "check-and-infer-return-any",
+              "skip-and-infer-return-any"
+            ]
+          }
+        },
+        "required": ["matches"],
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/src/schemas/json/pyrefly.json b/src/schemas/json/pyrefly.json
new file mode 100644
index 00000000000..c15d87fc6ea
--- /dev/null
+++ b/src/schemas/json/pyrefly.json
@@ -0,0 +1,140 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Pyrefly Configuration",
+  "description": "Schema for pyrefly.toml configuration file",
+  "type": "object",
+  "properties": {
+    "project-includes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Files to include as sources (user-space code)",
+      "default": ["**/*"]
+    },
+    "project-excludes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Files to exclude from sources",
+      "default": ["**/*venv/**"]
+    },
+    "search-path": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of directories where imports are resolved from"
+    },
+    "typeshed-path": {
+      "type": "string",
+      "description": "Override bundled typeshed with custom path"
+    },
+    "python-interpreter": {
+      "type": "string",
+      "description": "Path to Python executable for environment querying"
+    },
+    "python-platform": {
+      "type": "string",
+      "description": "Platform for sys.platform checks",
+      "enum": ["darwin", "linux", "win32"]
+    },
+    "python-version": {
+      "type": "string",
+      "description": "Python version string",
+      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
+    },
+    "site-package-path": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of directories containing third-party packages"
+    },
+    "conda-environment": {
+      "type": "string",
+      "description": "Name of conda environment to use"
+    },
+    "untyped-def-behavior": {
+      "type": "string",
+      "description": "How to handle untyped function definitions",
+      "enum": [
+        "check-and-infer-return-type",
+        "check-and-infer-return-any",
+        "skip-and-infer-return-any"
+      ],
+      "default": "check-and-infer-return-type"
+    },
+    "replace-imports-with-any": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Module patterns to replace with typing.Any"
+    },
+    "ignore-errors-in-generated-code": {
+      "type": "boolean",
+      "description": "Ignore errors in generated code (marked with @generated)",
+      "default": false
+    },
+    "use-untyped-imports": {
+      "type": "boolean",
+      "description": "Skip py.typed checks for site-package imports",
+      "default": true
+    },
+    "ignore-missing-source": {
+      "type": "boolean",
+      "description": "Skip checks for missing non-stub packages",
+      "default": true
+    },
+    "permissive-ignores": {
+      "type": "boolean",
+      "description": "Consider any ignore comment to suppress errors",
+      "default": false
+    },
+    "errors": {
+      "type": "object",
+      "description": "Enable/disable specific error types",
+      "properties": {
+        "assert-type": { "type": "boolean" },
+        "bad-argument-count": { "type": "boolean" },
+        "bad-argument-type": { "type": "boolean" },
+        "bad-assignment": { "type": "boolean" },
+        "bad-return": { "type": "boolean" },
+        "invalid-inheritance": { "type": "boolean" },
+        "missing-return": { "type": "boolean" },
+        "undefined-import": { "type": "boolean" },
+        "undefined-variable": { "type": "boolean" },
+        "unused-import": { "type": "boolean" },
+        "unused-variable": { "type": "boolean" }
+      },
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "sub-config": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "matches": {
+            "type": "string",
+            "description": "File pattern to match"
+          },
+          "untyped-def-behavior": {
+            "type": "string",
+            "enum": [
+              "check-and-infer-return-type",
+              "check-and-infer-return-any",
+              "skip-and-infer-return-any"
+            ]
+          }
+        },
+        "required": ["matches"],
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/src/test/pyrefly-tool/basic.toml b/src/test/pyrefly-tool/basic.toml
new file mode 100644
index 00000000000..d9f8f222aef
--- /dev/null
+++ b/src/test/pyrefly-tool/basic.toml
@@ -0,0 +1,4 @@
+[tool.pyrefly]
+project-includes = ["src/**"]
+python-version = "3.9.0"
+search-path = ["src"]
\ No newline at end of file
diff --git a/src/test/pyrefly-tool/comprehensive.toml b/src/test/pyrefly-tool/comprehensive.toml
new file mode 100644
index 00000000000..0562d88cf6c
--- /dev/null
+++ b/src/test/pyrefly-tool/comprehensive.toml
@@ -0,0 +1,37 @@
+[tool.pyrefly]
+project-includes = ["src/**", "tests/**"]
+project-excludes = ["tests/fixtures/**", "**/*venv/**"]
+search-path = ["src", "lib"]
+typeshed-path = "/usr/local/lib/python3.9/site-packages/typeshed"
+python-interpreter = "/usr/bin/python3"
+python-platform = "darwin"
+python-version = "3.9.0"
+site-package-path = ["/usr/local/lib/python3.9/site-packages"]
+conda-environment = "myenv"
+untyped-def-behavior = "check-and-infer-return-any"
+replace-imports-with-any = ["requests.*", "numpy.*"]
+ignore-errors-in-generated-code = true
+use-untyped-imports = false
+ignore-missing-source = false
+permissive-ignores = true
+
+[tool.pyrefly.errors]
+assert-type = true
+bad-argument-count = true
+bad-argument-type = false
+bad-assignment = true
+bad-return = false
+invalid-inheritance = true
+missing-return = true
+undefined-import = true
+undefined-variable = true
+unused-import = false
+unused-variable = false
+
+[[tool.pyrefly.sub-config]]
+matches = "tests/**/*.py"
+untyped-def-behavior = "skip-and-infer-return-any"
+
+[[tool.pyrefly.sub-config]]
+matches = "scripts/**/*.py"
+untyped-def-behavior = "check-and-infer-return-any"
\ No newline at end of file
diff --git a/src/test/pyrefly/comprehensive.toml b/src/test/pyrefly/comprehensive.toml
new file mode 100644
index 00000000000..78fb7d68ac1
--- /dev/null
+++ b/src/test/pyrefly/comprehensive.toml
@@ -0,0 +1,15 @@
+project-includes = ["src/**", "tests/**"]
+project-excludes = ["tests/fixtures/**"]
+search-path = ["src", "lib"]
+python-version = "3.9.0"
+python-platform = "linux"
+untyped-def-behavior = "check-and-infer-return-type"
+ignore-errors-in-generated-code = true
+
+[errors]
+assert-type = true
+bad-return = false
+
+[[sub-config]]
+matches = "tests/**"
+untyped-def-behavior = "skip-and-infer-return-any"
\ No newline at end of file
diff --git a/src/test/pyrefly/minimal.toml b/src/test/pyrefly/minimal.toml
new file mode 100644
index 00000000000..fa6c923371f
--- /dev/null
+++ b/src/test/pyrefly/minimal.toml
@@ -0,0 +1 @@
+search-path = ["."]
\ No newline at end of file