The Graph command line interface.
As of today, the command line interface consists of five commands:
graph codegen
— generates TypeScript code for smart contract ABIs used in subgraphs.graph build
— compiles subgraphs to WebAssembly and deploys them to IPFS.graph deploy
— deploys subgraphs to a Graph Node.graph remove
— removes subgraphs from a Graph Node.graph auth
— saves access token for Graph Node to the system's keychain.
graph
takes a subgraph manifest (defaults to subgraph.yaml
) with references to
- a GraphQL schema,
- smart contract ABIs,
- mappings written in TypeScript/AssemblyScript.
It compiles the mappings to WebAssembly, builds a ready-to-use version of the subgraph saved to IPFS or a local directory for debugging, and deploys the subgraph to a Graph Node.
Subgraphs for The Graph are set up like a typical TypeScript
project. It is recommended to install graph-cli
as a local dependency
via package.json
and use npm
scripts for code generation and
building.
If you are just getting started with creating a subgraph, head to getting started. Eventually this guide will lead you back here.
For clarity, an example of the setup below can be found in the ENS subgraph repository.
libsecret
is used for storing access tokens, so you may need to install it
before getting started. Use one of the following commands depending on
your distribution:
- Debian/Ubuntu:
sudo apt-get install libsecret-1-dev
- Red Hat:
sudo yum install libsecret-devel
- Arch Linux:
sudo pacman -S libsecret
-
Create a project for the subgraph with a
package.json
etc. -
Add a
subgraph.yaml
subgraph manifest with a GraphQL schema etc. -
Add
@graphprotocol/graph-cli
and@graphprotocol/graph-ts
dependencies, with one of# NPM npm install --save-dev @graphprotocol/graph-cli \ @graphprotocol/graph-ts # Yarn yarn add --dev \ @graphprotocol/graph-cli \ @graphprotocol/graph-ts
-
Add the following
tsconfig.json
:{ "extends": "./node_modules/@graphprotocol/graph-ts/tsconfig.json", "compilerOptions": { "types": ["@graphprotocol/graph-ts"] } }
-
Add the following to
package.json
:{ "scripts": { "codegen": "graph codegen --output-dir types/", "build": "graph build", "build-ipfs": "graph build --ipfs /ip4/127.0.0.1/tcp/5001", "deploy": "graph deploy --ipfs /ip4/127.0.0.1/tcp/5001 --node http://127.0.0.1:8020 --subgraph-name <SUBGRAPH_NAME>" } }
Note: Replace the IP addresses and ports with any Graph Node you want to deploy the subgraph to.
-
Generate type definitions for contract ABIs used in the subgraph. with:
yarn codegen
This creates the
types/
folder. This folder does not need to be uploaded to GitHub, and the files within it should not be edited. -
Develop your
mapping.ts
against these generated types. If you are new to this process, you can head over to getting started for a beginner friendly walkthrough of The Graph. -
Build the subgraph with:
yarn build
-
Deploy your subgraph to a Graph Node. The following command builds and deploys the subgraph continuously as you are making changes to it:
graph \ deploy \ --watch \ --verbosity debug \ --node http://127.0.0.1:8020/ \ --ipfs /ip4/127.0.0.1/tcp/5001 \ --subgraph-name <SUBGRAPH_NAME>
Note: If the Graph Node you are deploying to requires authorization, make sure to authorize with the node using e.g.
graph auth http://127.0.0.
:8020 <ACCESS_TOKEN>` before deploying.
To remove a subgraph from the Graph Node, use:
graph \
remove \
--node http://127.0.0.1:8020/ \
--subgraph-name <SUBGRAPH_NAME>
Copyright © 2018 Graph Protocol, Inc. and contributors.
The Graph CLI is dual-licensed under the MIT license and the Apache License, Version 2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.