---
title: 'flexkit query'
description: "Run GraphQL queries and mutations against a project's API from the terminal."
---

# `flexkit query`

Runs a GraphQL query or mutation against the project's [GraphQL API](/docs/api/graphql) and prints the JSON response on stdout. It uses your CLI credentials, so you don't need to create an API token or set headers.

The operation can be inline text, a `.graphql` file, or `-` to read it from stdin. GraphQL errors are printed on stderr, and the command exits with code `1`, so scripts can stop on errors.

## Synopsis

```bash
flexkit query <operation|file|-> [--var <key=value>]... [--variables <json|@file|->] [--data-only] [--project <id>]
```

## Examples

```bash
# Query the first five products
flexkit query '{ products(limit: 5) { _id sku name { default } } }'

# Run a query from a file with variables
flexkit query ./queries/orders-by-status.graphql --var status=PAID --var limit=20

# Pass all variables at once from a JSON file
flexkit query ./mutations/update-price.graphql --variables @vars.json

# Pipe an operation in and keep only the data
cat query.graphql | flexkit query - --data-only | jq '.products[].name'

# Query another project than the linked one
flexkit query ./queries/products.graphql --project abcdefghij
```

A file with variables looks like any GraphQL document:

```graphql
# queries/orders-by-status.graphql
query OrdersByStatus($status: String!, $limit: Int) {
  orders(where: { status: { eq: $status } }, limit: $limit) {
    _id
    total
    customer {
      email
    }
  }
}
```

## Variables

- `--var key=value` sets one variable and can be repeated. Values are parsed as JSON when possible: `--var limit=20` is a number, `--var active=true` is a boolean, `--var 'ids=["a","b"]'` is a list, and anything else is a string. Dotted keys build objects: `--var input.price=10` sends `{ "input": { "price": 10 } }`.
- `--variables` takes a whole JSON object, inline, as `@file`, or `-` for stdin.

When you use both, `--var` values override the same keys from `--variables`.

## Options

| Option                         | Description                                                         |
| ------------------------------ | ------------------------------------------------------------------- |
| `--var <key=value>`            | Set one variable. Repeatable.                                       |
| `--variables <json\|@file\|->` | Set all variables from a JSON object.                               |
| `--data-only`                  | Print only the `data` object instead of the full GraphQL response.  |
| `-p`, `--project <id>`         | Project to query. Defaults to the [linked project](/docs/cli/link). |

You can also use all [global options](/docs/cli/global-options).

## Notes

- Your role and space memberships apply, exactly as in Studio: a viewer can query but can't run mutations.
- To explore the schema, run [`flexkit schema show`](/docs/cli/schema), or use the [Explorer](/docs/studio/explorer) in Studio.
- For simple reads and writes without GraphQL, use [`flexkit records`](/docs/cli/records).


---

[View full sitemap](/docs/sitemap.md)