---
title: query
description: API reference for the `turbo query` command
product: turborepo
type: reference
summary: All flags and options for the `turbo query` command that runs GraphQL queries against your monorepo.
related:
  - /docs/crafting-your-repository/upgrading
  - /docs/reference/system-environment-variables
---

# query

<ExperimentalBadge />

Run GraphQL queries against your monorepo.

```bash title="Terminal"
turbo query [query] [flags]
```

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

```bash title="Terminal"
turbo query
```

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

```bash title="Terminal"
turbo query "query { packages { items { name } } }"
```

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

```bash title="Terminal"
turbo query query.gql
```

Shorthands [#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.

affected [#affected]

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

```bash title="Terminal"
turbo query affected [flags]
```

With no flags, returns all affected tasks:

```bash title="Terminal"
turbo query affected
```

```json title="Output"
{
  "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`](/docs/reference/configuration#inputs) match a changed file, or if an upstream task dependency is affected.

--tasks [#--tasks]

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

```bash title="Terminal"
turbo query affected --tasks
turbo query affected --tasks build
turbo query affected --tasks build test
```

--packages [#--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:

```bash title="Terminal"
turbo query affected --tasks build --packages web
```

```bash title="Terminal"
turbo query affected --packages
turbo query affected --packages web
turbo query affected --packages web docs
```

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

--base [#--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.

```bash title="Terminal"
turbo query affected --base main
```

--head [#--head]

Head git ref for comparison. Defaults to `HEAD`.

Can also be set with the `TURBO_SCM_HEAD` environment variable.

```bash title="Terminal"
turbo query affected --head my-branch
```

--exit-code [#--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.

```bash title="Terminal"
turbo query affected --packages my-app --exit-code
```

| Condition                        | Exit code |
| -------------------------------- | --------- |
| Nothing affected                 | `0`       |
| Affected packages or tasks found | `1`       |
| Query error                      | `2`       |

Migrating from turbo-ignore [#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`](/docs/reference/configuration#inputs) configuration.

Flag mapping [#flag-mapping]

| `turbo-ignore`            | `turbo query affected`                   |
| ------------------------- | ---------------------------------------- |
| `npx turbo-ignore my-app` | `turbo query affected --packages my-app` |
| `--task build`            | `--tasks build`                          |
| `--fallback main`         | `--base main`                            |

Key differences [#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 [#ci-example]

```bash title="Terminal"
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 [#flags]

--schema [#--schema]

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

```bash title="Terminal"
turbo query --schema
```

--variables (-V) [#--variables--v]

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

```bash title="Terminal"
turbo query query.gql --variables vars.json
```

---

[View full sitemap](/sitemap.md)