---
title: "gql | Grafana Alloy documentation"
description: "Learn about the gql command"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# `gql`

> **EXPERIMENTAL**: This is an [experimental](/docs/release-life-cycle/) feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the `stability.level` [flag](/docs/alloy/next/reference/cli/run/) to `experimental`.

The `gql` command runs a GraphQL query against the [Alloy GraphQL API](../../http/graphql/). Use this command to query information from a running Alloy instance, such as build metadata, readiness, and component health.

The `gql` command doesn’t enable the GraphQL API. The target Alloy instance must run with the GraphQL API enabled.

## Usage

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
alloy gql [<FLAG> ...] <QUERY>
```

Replace the following:

- *`<FLAG>`* : One or more flags that define the GraphQL endpoint.
- *`<QUERY>`* : Required. The GraphQL query to run.

The `graphql` command is an alias for `gql`.

## Enable the GraphQL API

The GraphQL API is disabled by default. To enable it, start Alloy with the `--stability.level=experimental` and `--server.http.enable-graphql` flags:

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
alloy run --stability.level=experimental --server.http.enable-graphql <CONFIG_PATH>
```

Replace *`<CONFIG_PATH>`* with the Alloy configuration file or directory path.

## Query formats

The `gql` command accepts complete GraphQL queries. For example, you can run an anonymous query:

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
alloy gql '{ alloy { version isReady } }'
```

The command also accepts query body shorthand. When the query doesn’t start with `{`, `query`, `mutation`, or `subscription`, the command wraps it in `query { ... }`.

For example, the following command:

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
alloy gql 'alloy { version isReady }'
```

Runs this GraphQL query:

graphql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```graphql
query { alloy { version isReady } }
```

## Flags

The following flags are supported:

- `--endpoint`: Address of the GraphQL endpoint (default `"http://127.0.0.1:12345/graphql"`).

## Examples

To query build and readiness information from the default GraphQL endpoint, use the following command:

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
alloy gql 'alloy { isReady version }'
```

The output resembles the following:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "data": {
    "alloy": {
      "isReady": true,
      "version": "v1.14.0"
    }
  }
}
```

To query a GraphQL endpoint on a different address (including other Alloy deployments), use the `--endpoint` flag:

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
alloy gql --endpoint=http://localhost:12345/graphql 'components { id health { message } }'
```