{"id":13452103,"url":"https://github.com/hasura/graphqurl","last_synced_at":"2025-05-11T16:30:15.482Z","repository":{"id":37713760,"uuid":"141697449","full_name":"hasura/graphqurl","owner":"hasura","description":"curl for GraphQL with autocomplete, subscriptions and GraphiQL. Also a dead-simple universal javascript GraphQL client.","archived":false,"fork":false,"pushed_at":"2025-02-13T17:21:19.000Z","size":2767,"stargazers_count":3362,"open_issues_count":44,"forks_count":101,"subscribers_count":47,"default_branch":"main","last_synced_at":"2025-04-23T09:45:33.391Z","etag":null,"topics":["autocomplete","cli","curl","graphql","mutations","query","subscription"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hasura.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-20T10:15:46.000Z","updated_at":"2025-04-22T05:41:35.000Z","dependencies_parsed_at":"2024-02-04T16:20:27.252Z","dependency_job_id":"9f8da130-d892-4fb2-b28f-a5347b8dae3c","html_url":"https://github.com/hasura/graphqurl","commit_stats":{"total_commits":95,"total_committers":20,"mean_commits":4.75,"dds":0.6526315789473685,"last_synced_commit":"3f0a490ed8f5a5b2333c4ccde17ffa5f1da574a0"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasura%2Fgraphqurl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasura%2Fgraphqurl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasura%2Fgraphqurl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasura%2Fgraphqurl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hasura","download_url":"https://codeload.github.com/hasura/graphqurl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253595423,"owners_count":21933386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autocomplete","cli","curl","graphql","mutations","query","subscription"],"created_at":"2024-07-31T07:01:13.044Z","updated_at":"2025-05-11T16:30:15.449Z","avatar_url":"https://github.com/hasura.png","language":"JavaScript","funding_links":[],"categories":["graphql","JavaScript","Implementations","2. 调试工具"],"sub_categories":["JavaScript/TypeScript","24.3 Web Sockets"],"readme":"# graphqurl\n\n[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)\n[![Version](https://img.shields.io/npm/v/graphqurl.svg)](https://npmjs.org/package/graphqurl)\n\n[![Azure Pipelines](https://dev.azure.com/hasura/graphqurl/_apis/build/status/hasura.graphqurl?branchName=master)](https://dev.azure.com/hasura/graphqurl/_build/latest?definitionId=1\u0026branchName=master)\n[![Appveyor CI](https://ci.appveyor.com/api/projects/status/github/hasura/graphqurl?branch=master\u0026svg=true)](https://ci.appveyor.com/project/hasura-bot/graphqurl/branch/master)\n[![Downloads/week](https://img.shields.io/npm/dw/graphqurl.svg)](https://npmjs.org/package/graphqurl)\n[![License](https://img.shields.io/npm/l/graphqurl.svg)](https://github.com/hasura/graphqurl/blob/master/LICENSE)\n\u003c!--[![Codecov](https://codecov.io/gh/hasura/graphqurl/branch/master/graph/badge.svg)](https://codecov.io/gh/hasura/graphqurl)--\u003e\n\n`graphqurl` is a curl like CLI for GraphQL. It's features include:\n- CLI for making GraphQL queries. It also provisions queries with autocomplete.\n- Use as a library with Node.js or from the browser\n- Supports subscriptions\n- Export GraphQL schema\n\nNote: v2.0.0 onwards, support for GraphiQL (UI) is removed. See this [issue](https://github.com/hasura/graphqurl/issues/153) for more details. Use v1.0.3 for GraphiQL feature.\n\nMade with :heart: by \u003ca href=\"https://hasura.io\"\u003eHasura\u003c/a\u003e\n\n----------------\n![Graphqurl Demo](assets/subscription.gif)\n---\n![Subscriptions triggering bash](assets/bash_trigger.gif)\n\n----------------\n\n## Table of contents\n- [Installation](#installation)\n  * [Steps to Install CLI](#steps-to-install-cli)\n  * [Steps to Install Node Library](#steps-to-install-node-library)\n- [Usage](#usage)\n  * [CLI](#cli)\n    + [Query](#query)\n    + [Auto-complete](#auto-complete)\n    + [Subscription](#subscription)\n    + [Export schema](#export-schema)\n  * [Command](#command)\n    + [Args](#args)\n    + [Flag Reference](#flag-reference)\n  * [Node Library](#node-library)\n    + [Using callbacks:](#using-callbacks)\n    + [Using Promises:](#using-promises)\n  * [API](#api)\n    + [createClient(options)](#createclient)\n    + [Client](#client)\n- [More Examples](#more-examples)\n  * [Node Library](#node-library-1)\n    + [Queries and Mutations](#queries-and-mutations)\n    + [Subscriptions](#subscriptions)\n  * [CLI](#cli-1)\n\n\n## Installation\n\n### Steps to Install CLI\n\n```bash\nnpm install -g graphqurl\n```\n\n### Steps to Install Node Library\n\n```bash\nnpm install --save graphqurl\n```\n\n## Usage\n\n### CLI\n\n#### Query\n\n```bash\ngq https://my-graphql-endpoint/graphql \\\n     -H 'Authorization: Bearer \u003ctoken\u003e' \\\n     -q 'query { table { column } }'\n```\n\n#### Auto-complete\n\nGraphqurl can auto-complete queries using schema introspection. Execute the\ncommand without providing a query string:\n\n```bash\n$ gq \u003cendpoint\u003e [-H \u003cheader:value\u003e]\nEnter the query, use TAB to auto-complete, Ctrl+Q to execute, Ctrl+C to cancel\ngql\u003e\n```\n\nYou can use `TAB` to trigger auto-complete. `Ctrl+C` to cancel the input and\n`Ctrl+Q`/`Enter` to execute the query.\n\n#### Subscription\n\nSubscriptions can be executed and the response is streamed on to stdout.\n\n```bash\ngq \u003cendpoint\u003e \\\n   -q 'subscription { table { column } }'\n```\n\n#### Export schema\n\nExport GraphQL schema to GraphQL or JSON format:\n\n```bash\ngq \u003cendpoint\u003e --introspect \u003e schema.graphql\n\n# json\ngq \u003cendpoint\u003e --introspect --format json \u003e schema.json\n```\n\n### Command\n\n```bash\n$ gq ENDPOINT [-q QUERY]\n```\n\n#### Args\n\n* `ENDPOINT`: graphql endpoint (can be also set as `GRAPHQURL_ENDPOINT` env var)\n\n#### Flag Reference\n\n| Flag                | Shorthand | Description                                                                                           |\n|---------------------|-----------|-------------------------------------------------------------------------------------------------------|\n| `--query`           | `-q`      | GraphQL query to execute                                                                              |\n| `--header`          | `-H`      | request header                                                                                        |\n| `--variable`        | `-v`      | Variables used in the query                                                                           |\n| `--variablesJSON`   | `-n`      | Variables used in the query as JSON                                                                   |\n| `--singleLine`      | `-l`      | Prints output in a single line, does not prettify                                                     |\n| `--introspect`      |           | Introspect the endpoint and get schema                                                                |\n| `--format`          |           | Output format for GraphQL schema after introspection. Options: `json`, `graphql` (Default: `graphql`) |\n| `--help`            | `-h`      | Outputs the command help text                                                                         |\n| `--version`         |           | Outputs CLI version                                                                                   |\n|`--queryFile`        |           | File to read the query from                                                                           |\n|`--operationName`    |           | Name of the operation to execute from the query file                                                  |\n|`--variablesFile`    |           | JSON file to read the query variables from                                                            |\n\n\n### Node Library\n\n#### Using callbacks:\n\n```js\nconst { createClient } = require('graphqurl');\n\nconst client = createClient({\n  endpoint: 'https://my-graphql-endpoint/graphql',\n  headers: {\n    'Authorization': 'Bearer \u003ctoken\u003e'\n  }\n});\n\nfunction successCallback(response, queryType, parsedQuery) {\n  if (queryType === 'subscription') {\n    // handle subscription response\n  } else {\n    // handle query/mutation response\n  }\n}\n\nfunction errorCallback(error, queryType, parsedQuery) {\n  console.error(error);\n}\n\nclient.query(\n  {\n    query: 'query ($id: Int) { table_by_id (id: $id) { column } }',\n    variables: { id: 24 }\n  },\n  successCallback,\n  errorCallback\n);\n\n```\n\n#### Using Promises:\n\nFor queries and mutations,\n\n```js\nconst { createClient } = require('graphqurl');\n\nconst client = createClient({\n  endpoint: 'https://my-graphql-endpoint/graphql',\n  headers: {\n    'Authorization': 'Bearer \u003ctoken\u003e'\n  }\n});\n\nclient.query(\n  {\n    query: 'query ($id: Int) { table_by_id (id: $id) { column } }',\n    variables: { id: 24 }\n  }\n).then((response) =\u003e console.log(response))\n .catch((error) =\u003e console.error(error));\n```\n\nFor subscriptions,\n\n```js\nconst { createClient } = require('graphqurl');\n\nconst client = createClient({\n  endpoint: 'https://my-graphql-endpoint/graphql',\n  headers: {\n    'Authorization': 'Bearer \u003ctoken\u003e'\n  },\n  websocket: {\n    endpoint: 'wss://my-graphql-endpoint/graphql',\n    onConnectionSuccess: () =\u003e console.log('Connected'),\n    onConnectionError: () =\u003e console.log('Connection Error'),\n  }\n});\n\nclient.subscribe(\n  {\n    subscription: 'subscription { table { column } }',\n  },\n  (event) =\u003e {\n    console.log('Event received: ', event);\n    // handle event\n  },\n  (error) =\u003e {\n    console.log('Error: ', error);\n    // handle error\n  }\n)\n```\n\n### API\n\n#### createClient\n\nThe `createClient` function is available as a named export. It takes init options and returns `client`.\n\n```\nconst { createClient } = require('graphqurl');\n```\n\n\n- **options**: [Object, *required*] graphqurl init options with the following properties:\n  - endpoint: [String, *required*] GraphQL endpoint\n  - headers: [Object] Request header, defaults to `{}`. These headers will be added along with all the GraphQL queries, mutations and subscriptions made through the client.\n  - websocket: [Object] Options for configuring subscriptions over websocket. Subscriptions are not supported if this field is empty.\n    - endpoint: [String, ] WebSocket endpoint to run GraphQL subscriptions.\n    - shouldRetry: [Boolean] Boolean value whether to retry closed websocket connection. Defaults to false.\n    - parameters: [Object] Payload to send the connection init message with\n    - onConnectionSuccess: [void =\u003e void] Callback function called when the GraphQL connection is successful. Please not that this is different from the websocket connection being open. Please check the [followed protocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md) for more details.\n    - onConnectionError: [error =\u003e null] Callback function called if the GraphQL connection over websocket is unsuccessful\n    - onConnectionKeepAlive: [void =\u003e null]: Callback function called when the GraphQL server sends `GRAPHQL_CONNECTION_KEEP_ALIVE` messages to keep the connection alive.\n\n- **Returns**: [client]\n\n#### Client\n\n\n```js\nconst client = createClient({\n  endpoint: 'https://my-graphql-endpoint/graphql'\n});\n```\n\nThe graphqurl client exposeses the following methods:\n\n- **client.query**: [(queryoptions, successCallback, errorCallback) =\u003e Promise (response)]\n  - queryOptions: [Object *required*]\n    - query: [String *required*] The GraphQL query or mutation to be executed over HTTP\n    - variables: [Object] GraphQL query variables. Defaults to `{}`\n    - headers: [Object] Header overrides. If you wish to make a GraphQL query while adding to or overriding the headers provided during initalisations, you can pass the headers here.\n  - successCallback: [response =\u003e null] Success callback which is called after a successful response. It is called with the following parameters:\n    - response: The response of your query\n  - errorCallback: [error =\u003e null] Error callback which is called after the occurrence of an error. It is called with the following parameters:\n    - error: The occurred error\n  - **Returns**: [Promise (response) ] This function returns the response wrapped in a promise.\n    - response: response is a GraphQL compliant JSON object in case of `queries` and `mutations`.\n\n- **client.subscribe**: [(subscriptionOptions, eventCallback, errorCallback) =\u003e Function (stop)]\n  - subscriptionOptions: [Object *required*]\n    - subscription: [String *required*] The GraphQL subscription to be started over WebSocket\n    - variables: [Object] GraphQL query variables. Defaults to `{}`\n    - onGraphQLData: [(response) =\u003e null] You can optionally pass this function as an event callback\n    - onGraphQLError: [(response) =\u003e null] You can optionally pass this function as an error callback\n    - onGraphQLComplete: [() =\u003e null] Callback function called when the GraphQL subscription is declared as `complete` by the server and no more events will be received\n  - eventCallback: [(response) =\u003e null] Event callback which is called after receiving an event from the given subscription. It is called with the following parameters:\n    - event: The received event from the subscription\n  - errorCallback: [error =\u003e null] Error callback which is called after the occurrence of an error. It is called with the following parameters:\n    - error: The occurred error\n  - **Returns**: [void =\u003e null] This is a function to stop the subscription\n\n\n## More Examples\n\n### Node Library\n\n#### Queries and Mutations\n\nQuery example with variables\n\n```js\nconst { createClient } = require('graphqurl');\n\nconst client = createClient({\n  endpoint: 'https://my-graphql-endpoint/graphql',\n  headers: {\n    'x-access-key': 'mysecretxxx',\n  },\n});\n\nclient.query(\n  {\n    query: `\n      query ($name: String) {\n        table(where: { column: $name }) {\n          id\n          column\n        }\n      }\n    `,\n    variables: {\n      name: 'Alice'\n    }\n  }\n).then((response) =\u003e console.log(response))\n .catch((error) =\u003e console.error(error));\n```\n\n#### Subscriptions\n\nUsing promises,\n\n```js\nconst { createClient } = require('graphqurl');\nconst client = createClient({\n  endpoint: 'https://my-graphql-endpoint/graphql',\n  headers: {\n    'Authorization': 'Bearer Andkw23kj=Kjsdk2902ksdjfkd'\n  }\n  websocket: {\n    endpoint: 'wss://my-graphql-endpoint/graphql',\n  }\n})\n\nconst eventCallback = (event) =\u003e {\n  console.log('Event received:', event);\n  // handle event\n};\n\nconst errorCallback = (error) =\u003e {\n  console.log('Error:', error)\n};\n\nclient.subscribe(\n  {\n    query: 'subscription { table { column } }',\n  },\n  eventCallback,\n  errorCallback\n)\n```\n\n\n### CLI\n\nGeneric example:\n\n```bash\ngq \\\n     https://my-graphql-endpoint/graphql \\\n     -H 'Authorization: Bearer \u003ctoken\u003e' \\\n     -H 'X-Another-Header: another-header-value' \\\n     -v 'variable1=value1' \\\n     -v 'variable2=value2' \\\n     -q 'query { table { column } }'\n```\n\n---\nMaintained with :heart: by \u003ca href=\"https://hasura.io\"\u003eHasura\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasura%2Fgraphqurl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhasura%2Fgraphqurl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasura%2Fgraphqurl/lists"}