query

Run GraphQL queries against your monorepo.

turbo query [query] [flags]

To quickly get the GraphQL schema, use the --schemaflag.

turbo query --schema

When no arguments are passed, the command will open a GraphiQL playground to run queries.

turbo query

When passed a query string, the command will run the query and output the results.

turbo query "query { packages { items { name } } }"

When passed a file path, the command will read the file and run the query.

turbo query query.gql

Shorthands

Shorthands generate GraphQL queries for common operations so you don't need to write them by hand. The JSON output is identical to what you'd get from a raw query.

ls

List packages in your monorepo. This is a shorthand for a packages query, equivalent to turbo ls.

turbo query ls [packages] [flags]

With no arguments, lists all packages:

turbo query ls

{
  "packageManager": "npm",
  "packages": {
    "count": 3,
    "items": [
      { "name": "docs", "path": "apps/docs" },
      { "name": "ui", "path": "packages/ui" },
      { "name": "web", "path": "apps/web" }
    ]
  }
}

When passed package names, returns detailed information including tasks, dependencies, and dependents:

turbo query ls web

--filter (-F)

Use pnpm-style package selectors to narrow the package list. Same syntax as turbo run --filter.

turbo query ls --filter=web...
turbo query ls -F my-app...

--affected

Show only packages affected by changes between the current branch and main.

When combined with --filter, returns the intersection: only packages that are both affected and match the filter.

turbo query ls --affected
turbo query ls --affected --filter=web

--output

Control the output format. Defaults to pretty (human-readable).

turbo query ls --output json
turbo query ls --output pretty

affected

Check which packages or tasks are affected by changes between two git refs.

turbo query affected [flags]

For example, setting up Git to check out with --filter=blob:none --depth=0 will ensure turbo query affected has the right history to work correctly.

With no flags, returns all affected tasks:

turbo query affected

{
  "data": {
    "affectedTasks": {
      "items": [
        {
          "name": "build",
          "fullName": "web#build",
          "package": { "name": "web" },
          "reason": { "__typename": "TaskFileChanged" }
        }
      ],
      "length": 1
    }
  }
}

Task-level detection is more precise than package-level. A task is only reported as affected if its configured inputs match a changed file, or if an upstream task dependency is affected.

--tasks

Filter to specific task names. With no values, returns all affected tasks (same as bare turbo query affected).

turbo query affected --tasks
turbo query affected --tasks build
turbo query affected --tasks build test

--packages

Without --tasks, returns affected packages instead of tasks. With no values, returns all affected packages. With values, filters to the named packages.

When combined with --tasks, both filters apply (intersection) — only tasks matching the task name and belonging to the named packages are returned. This lets you check whether a specific task in a specific package changed:

turbo query affected --tasks build --packages web

turbo query affected --packages
turbo query affected --packages web
turbo query affected --packages web docs

{
  "data": {
    "affectedPackages": {
      "items": [
        {
          "name": "web",
          "path": "apps/web",
          "reason": { "__typename": "FileChanged" }
        }
      ],
      "length": 1
    }
  }
}

--base

Base git ref for comparison. Defaults to the auto-detected base (e.g. GITHUB_BASE_REF on GitHub Actions, or the merge-base with main).

Can also be set with the TURBO_SCM_BASE environment variable. When both are provided, --base takes precedence.

turbo query affected --base main

--head

Head git ref for comparison. Defaults to HEAD.

Can also be set with the TURBO_SCM_HEAD environment variable. When both are provided, --head takes precedence.

turbo query affected --head my-branch

--exit-code

Exit with code 1 when affected packages or tasks are found, 0 when none are found, or 2 on errors. JSON output is still printed to stdout.

We recommend parsing the JSON output directly for most use cases since it gives you the reason for each change and lets you make more nuanced decisions. --exit-code is available as a shorthand for simple cases.

turbo query affected --packages my-app --exit-code

Migrating from turbo-ignore

turbo-ignore is deprecated. turbo query affected is its replacement, with more precise task-level change detection that respects your inputs configuration.

Flag mapping

Key differences

• More precise detection: turbo-ignore operates at the package level. turbo query affected operates at the task input level, so a .md change won't trigger a rebuild if your task excludes *.md files via inputs.
• Structured output: The JSON output includes the reason each package or task is affected, which is useful for debugging and automation.

CI example

affected=$(turbo query affected --packages my-app)
count=$(echo "$affected" | jq '.data.affectedPackages.length')

if [ "$count" -gt 0 ]; then
  echo "my-app is affected, proceeding with build"
else
  echo "my-app is not affected, skipping"
  exit 0
fi

Flags

--schema

Output the GraphQL introspection schema. Cannot be used with a query argument.

turbo query --schema

--variables (-V)

Path to a JSON file containing query variables. Requires a query argument.

turbo query query.gql --variables vars.json