feat: add --project-dir option to dbt-score lint

Allow linting a dbt project that is not the current working directory,
similar to dbt's own `--project-dir` option. The directory is used to
locate `manifest.json` (unless `--manifest` is given) and is passed on to
`dbt parse` and `dbt ls` when dbt is invoked.

Closes #67

Author: DG47

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to
 
 ## [Unreleased]
 
+- Add `--project-dir` option to `dbt-score lint` to lint a dbt project located
+  outside of the current working directory (#67).
+
 ## [0.19.0] - 2026-10-07
 
 - Drop support for Python 3.10. The minimum required version is now 3.11.

README.md

@@ -69,6 +69,9 @@ dbt-score lint --exclude my_model+
 
 # Auto-generate manifest (via `dbt parse`) and lint
 dbt-score lint --run-dbt-parse
+
+# Lint a dbt project in another directory
+dbt-score lint --project-dir path/to/dbt_project --run-dbt-parse
 ```
 
 ### Example Output

docs/get_started.md

@@ -40,6 +40,14 @@ It's also possible to automatically run `dbt parse`, to generate the
 dbt-score lint --run-dbt-parse
 ```
 
+To lint a dbt project located outside of the current working directory, use the
+`--project-dir` option. Similar to dbt, `dbt-score` will look for the project
+and its `manifest.json` in that directory, and run dbt from there:
+
+```shell
+dbt-score lint --project-dir path/to/dbt_project --run-dbt-parse
+```
+
 To lint only a selection of dbt entities, the argument `--select` can be used.
 It accepts any
 [dbt node selection syntax](https://docs.getdbt.com/reference/node-selection/syntax):

src/dbt_score/cli.py

@@ -73,12 +73,20 @@ def cli() -> None:
     default=None,
     multiple=True,
 )
+@click.option(
+    "--project-dir",
+    help="Directory of the dbt project. Used to locate the manifest and to run "
+    "dbt. Defaults to the current working directory.",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=None,
+)
 @click.option(
     "--manifest",
     "-m",
-    help="Manifest filepath.",
+    help="Manifest filepath. Defaults to `manifest.json` in the target directory "
+    "of the dbt project.",
     type=click.Path(path_type=Path),
-    default=get_default_manifest_path(),
+    default=None,
 )
 @click.option(
     "--run-dbt-parse",
@@ -129,7 +137,8 @@ def lint(  # noqa: PLR0913, C901, PLR0912
     exclude: tuple[str, ...],
     namespace: list[str],
     disabled_rule: list[str],
-    manifest: Path,
+    project_dir: Path | None,
+    manifest: Path | None,
     run_dbt_parse: bool,
     fail_project_under: float | None,
     fail_any_item_under: float | None,
@@ -143,6 +152,8 @@ def lint(  # noqa: PLR0913, C901, PLR0912
     )
     if manifest_provided and run_dbt_parse:
         raise click.UsageError("--run-dbt-parse cannot be used with --manifest.")
+    if manifest is None:
+        manifest = get_default_manifest_path(project_dir)
 
     config = Config()
     config.load()
@@ -161,13 +172,14 @@ def lint(  # noqa: PLR0913, C901, PLR0912
 
     try:
         if run_dbt_parse:
-            dbt_parse()
+            dbt_parse(project_dir=project_dir)
         evaluation = lint_dbt_project(
             manifest_path=manifest,
             config=config,
             format=format,
             select=select,
             exclude=exclude,
+            project_dir=project_dir,
         )
 
     except FileNotFoundError:

src/dbt_score/dbt_utils.py

@@ -65,17 +65,25 @@ def _disable_dbt_stdout() -> Iterator[None]:
 
 
 @dbt_required
-def dbt_parse() -> "dbtRunnerResult":
+def dbt_parse(project_dir: Path | None = None) -> "dbtRunnerResult":
     """Parse a dbt project.
 
+    Args:
+        project_dir: The dbt project directory. Defaults to the directory dbt
+            would use on its own, i.e. the current working directory.
+
     Returns:
         The dbt parse run result.
 
     Raises:
         DbtParseException: dbt parse failed.
     """
+    cmd = ["parse"]
+    if project_dir is not None:
+        cmd += ["--project-dir", str(project_dir)]
+
     with _disable_dbt_stdout():
-        result: "dbtRunnerResult" = dbtRunner().invoke(["parse"])
+        result: "dbtRunnerResult" = dbtRunner().invoke(cmd)
 
     if not result.success:
         raise DbtParseException(root_cause=result.exception)
@@ -85,7 +93,9 @@ def dbt_parse() -> "dbtRunnerResult":
 
 @dbt_required
 def dbt_ls(
-    select: Iterable[str] | None, exclude: Iterable[str] | None = None
+    select: Iterable[str] | None,
+    exclude: Iterable[str] | None = None,
+    project_dir: Path | None = None,
 ) -> Iterable[str]:
     """Run dbt ls."""
     cmd = [
@@ -103,6 +113,8 @@ def dbt_ls(
         cmd += ["--select", *select]
     if exclude:
         cmd += ["--exclude", *exclude]
+    if project_dir is not None:
+        cmd += ["--project-dir", str(project_dir)]
 
     with _disable_dbt_stdout():
         result: "dbtRunnerResult" = dbtRunner().invoke(cmd)
@@ -114,11 +126,17 @@ def dbt_ls(
     return selected
 
 
-def get_default_manifest_path() -> Path:
-    """Get the manifest path."""
-    return (
-        Path().cwd()
-        / os.getenv("DBT_PROJECT_DIR", "")
-        / os.getenv("DBT_TARGET_DIR", "target")
-        / "manifest.json"
-    )
+def get_default_manifest_path(project_dir: Path | None = None) -> Path:
+    """Get the manifest path.
+
+    Args:
+        project_dir: The dbt project directory. Defaults to the current working
+            directory, combined with the `DBT_PROJECT_DIR` environment variable
+            if it is set.
+
+    Returns:
+        The path of `manifest.json` in the target directory of the project.
+    """
+    if project_dir is None:
+        project_dir = Path.cwd() / os.getenv("DBT_PROJECT_DIR", "")
+    return project_dir / os.getenv("DBT_TARGET_DIR", "target") / "manifest.json"

src/dbt_score/lint.py

@@ -20,6 +20,7 @@ def lint_dbt_project(
     format: Literal["plain", "manifest", "ascii", "json"],
     select: Iterable[str] | None = None,
     exclude: Iterable[str] | None = None,
+    project_dir: Path | None = None,
 ) -> Evaluation:
     """Lint dbt manifest."""
     if not manifest_path.exists():
@@ -28,7 +29,9 @@ def lint_dbt_project(
     rule_registry = RuleRegistry(config)
     rule_registry.load_all()
 
-    manifest_loader = ManifestLoader(manifest_path, select=select, exclude=exclude)
+    manifest_loader = ManifestLoader(
+        manifest_path, select=select, exclude=exclude, project_dir=project_dir
+    )
 
     formatters = {
         "plain": HumanReadableFormatter,

src/dbt_score/models.py

@@ -741,14 +741,18 @@ def __init__(
         file_path: Path,
         select: Iterable[str] | None = None,
         exclude: Iterable[str] | None = None,
+        project_dir: Path | None = None,
     ):
         """Initialize the ManifestLoader.
 
         Args:
             file_path: The file path of the JSON manifest.
             select: An optional dbt selection.
             exclude: An optional dbt exclusion.
+            project_dir: An optional dbt project directory, used when the
+                selection requires running dbt.
         """
+        self.project_dir = project_dir
         self.raw_manifest = json.loads(file_path.read_text(encoding="utf-8"))
         self.project_name = self.raw_manifest["metadata"]["project_name"]
         self.raw_nodes = {
@@ -913,7 +917,7 @@ def _filter_evaluables(
 
         else:
             # Use dbt's implementation of --select and --exclude
-            result_list = dbt_ls(select, exclude)
+            result_list = dbt_ls(select, exclude, project_dir=self.project_dir)
 
         self.models = {k: m for k, m in self.models.items() if m.name in result_list}
         self.sources = {

tests/test_cli.py

@@ -1,5 +1,7 @@
 """Test the CLI."""
 
+import shutil
+from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 from click.testing import CliRunner
@@ -63,6 +65,92 @@ def test_lint_unparseable_manifest(tmp_path, caplog):
     assert "dbt's manifest.json could not be parsed" in caplog.text
 
 
+def passing_evaluation() -> MagicMock:
+    """Return a mock evaluation with passing scores."""
+    mock_eval = MagicMock()
+    mock_eval.project_score = Score(10.0, "🥇")
+    mock_eval.scores = {}
+    return mock_eval
+
+
+def test_lint_project_dir(tmp_path, manifest_path):
+    """Test lint with a project directory, which is used to find the manifest."""
+    runner = CliRunner()
+    project_dir = tmp_path / "my_project"
+    (project_dir / "target").mkdir(parents=True)
+    shutil.copy(manifest_path, project_dir / "target" / "manifest.json")
+
+    with (
+        patch("dbt_score.cli.Config._load_toml_file"),
+        patch("dbt_score.cli.lint_dbt_project") as mock_lint_dbt_project,
+    ):
+        mock_lint_dbt_project.return_value = passing_evaluation()
+        result = runner.invoke(
+            lint, ["--project-dir", str(project_dir)], catch_exceptions=False
+        )
+
+    assert result.exit_code == 0
+    assert mock_lint_dbt_project.call_args.kwargs["manifest_path"] == (
+        project_dir / "target" / "manifest.json"
+    )
+    assert mock_lint_dbt_project.call_args.kwargs["project_dir"] == project_dir
+
+
+def test_lint_project_dir_with_manifest(tmp_path, manifest_path):
+    """Test lint with a project directory and an explicit manifest."""
+    runner = CliRunner()
+
+    with (
+        patch("dbt_score.cli.Config._load_toml_file"),
+        patch("dbt_score.cli.lint_dbt_project") as mock_lint_dbt_project,
+    ):
+        mock_lint_dbt_project.return_value = passing_evaluation()
+        result = runner.invoke(
+            lint,
+            ["--project-dir", str(tmp_path), "--manifest", str(manifest_path)],
+            catch_exceptions=False,
+        )
+
+    assert result.exit_code == 0
+    assert mock_lint_dbt_project.call_args.kwargs["manifest_path"] == Path(
+        manifest_path
+    )
+    assert mock_lint_dbt_project.call_args.kwargs["project_dir"] == tmp_path
+
+
+def test_lint_project_dir_run_dbt_parse(tmp_path):
+    """Test lint with a project directory and dbt parse."""
+    runner = CliRunner()
+    project_dir = tmp_path / "my_project"
+    project_dir.mkdir()
+
+    with (
+        patch("dbt_score.cli.Config._load_toml_file"),
+        patch("dbt_score.cli.dbt_parse") as mock_dbt_parse,
+        patch("dbt_score.cli.lint_dbt_project") as mock_lint_dbt_project,
+    ):
+        mock_lint_dbt_project.return_value = passing_evaluation()
+        result = runner.invoke(
+            lint,
+            ["--project-dir", str(project_dir), "--run-dbt-parse"],
+            catch_exceptions=False,
+        )
+
+    assert result.exit_code == 0
+    mock_dbt_parse.assert_called_once_with(project_dir=project_dir)
+
+
+def test_lint_project_dir_non_existing(tmp_path):
+    """Test lint with a non-existing project directory."""
+    runner = CliRunner()
+
+    with patch("dbt_score.cli.Config._load_toml_file"):
+        result = runner.invoke(lint, ["--project-dir", str(tmp_path / "nope")])
+
+    assert result.exit_code == 2
+    assert "does not exist" in result.output
+
+
 def test_lint_dbt_parse_exception(caplog):
     """Test lint with a dbt parse error."""
     runner = CliRunner()