Skip to content

Developer workflow

Store your GraphOps API key in the macOS Keychain or Linux Secret Service, check which key is in use, and call RPC, Subgraphs and Substreams with it from your terminal and your own code.

Build against GraphOps without pasting an API key into .env files, shell profiles or command history. Store the key once in your operating system's credential store, then let graphops hand it to each command or application you run, and to nothing else.

This page follows a typical local loop: store a key, check what is configured, then call each data service with it.

Prerequisites

  • The GraphOps CLI, signed in to your organization with graphops auth login.
  • The owner or developer role, to create a key. Creating a key also needs a sign-in from the last 12 hours.

Store an API key in your credential store

CLI · GraphOps CLI

# Create an API key for every data service your organization can use, and store it in your
# operating system's credential store. The secret is never printed.
graphops api-keys create --store --name laptop

# Or store a key you already have: paste it at the prompt, which does not echo it.
graphops api-keys store

graphops api-keys create --store creates a query key with every data service your organization can use and stores it without printing it. Pass --product rpc (repeat for several) to grant only some. graphops api-keys store reads a key you already created in API keys from a prompt that does not echo it, or from standard input as in pbpaste | graphops api-keys store. The CLI checks that the key is an active key of your organization before storing it.

Where the key is kept

The CLI keeps your sign-in session and each organization's stored key in your operating system's credential store:

SystemCredential store
macOSThe login Keychain. macOS can ask you to allow graphops to read it.
Linux desktopThe Secret Service, such as GNOME Keyring or KWallet.
WindowsWindows Credential Manager.

Entries are filed under the service graphops-cli. The CLI's configuration directory keeps only metadata about the key, such as its ID, name, data services and last four characters, never the secret.

Where no credential store is available, such as a Linux server without a desktop session or an SSH session on Windows, the CLI keeps secrets in secrets.toml in its configuration directory and prints a warning whenever it uses that file. On macOS and Linux the file is readable only by you, and the CLI refuses to read it once other users can. On Windows it is protected only by its folder's permissions. Anyone with your user account or a copy of the file can use the secrets. On a server or in CI, set GRAPHOPS_API_KEY instead, which is never stored; see Scripts, CI and coding agents.

Check what is configured

CLI · GraphOps CLI

# Who is signed in, the organization, and where secrets live: "secret store: keychain".
graphops auth status

# The key graphops exec uses: its ID, name, data services and last four characters.
graphops api-keys current

# Check the whole setup, including that the stored key is still active.
graphops doctor
  • graphops auth status shows who is signed in, the organization commands act in, and which store holds your secrets: secret store: keychain for the operating system's credential store, or secret store: file <path> for secrets.toml.
  • graphops api-keys current shows the key your commands use: its ID, name, data services and last four characters. When GRAPHOPS_API_KEY is set in your shell, it reports that variable's key instead, because the variable takes precedence over the stored key. --reveal also prints the secret.
  • graphops doctor checks your sign-in, organization, credential store, that the stored key is still active, and the variables graphops exec sets. It prints a fix for each check that fails.

Switch organization, replace or forget a key

CLI · GraphOps CLI

# Each organization has its own stored key: switching organization switches the key.
graphops orgs use other-organization
graphops api-keys current

# Replace the stored key. The previous key keeps working until you revoke it.
graphops api-keys create --store --replace --name laptop

# Forget the stored key. Forgetting does not revoke it.
graphops api-keys forget

Each organization has its own stored key. After graphops orgs use <organization>, or with --organization, commands use that organization's key, never the previous one. Each configuration profile (--profile) and configuration directory (GRAPHOPS_CONFIG_DIR) keeps its own keys too.

graphops api-keys create --store --replace stores a new key in place of the old one and names the old key, which keeps working until you revoke it. graphops api-keys forget removes the stored key from your machine without revoking it. To stop a key working, revoke it with graphops api-keys revoke; see Manage keys and service accounts.

Run your code with the key

CLI · GraphOps CLI

# Run your application with the key in GRAPHOPS_API_KEY, set for this process only.
graphops exec node index.js

# Options for graphops exec go first; everything after the command is passed to it unchanged.
graphops exec --product rpc -- npm run dev

graphops exec runs your command with the key in GRAPHOPS_API_KEY, the variable every GraphOps code example reads, and in no other process. When the key covers Substreams, it is also set as SUBSTREAMS_API_KEY. The key stays out of your shell history and your shell's environment, but anything your code prints, including its environment, can show it.

  • Put the exec options first. Everything from your command onward is passed to it unchanged, even arguments such as --help. A -- before your command is optional.
  • --product <service> checks that the stored key covers a data service before your command runs, and exits 125 without running it if not. The CLI cannot check a key you set in GRAPHOPS_API_KEY, so it runs your command with that key as given.
  • Your command's output and exit code are its own. When graphops exec fails before your command starts, for example because no key is stored, it exits 125, so a script or process supervisor can tell its failures from your program's.

When the key covers Substreams, or with --product substreams, your command does not receive the Substreams endpoint or credential variables your shell already has, such as SUBSTREAMS_ENDPOINT or SUBSTREAMS_API_TOKEN, so an endpoint set for another provider cannot receive your GraphOps key. Instead, every network GraphOps serves points at its GraphOps endpoint. Add --network <network> to also set SUBSTREAMS_ENDPOINT to the GraphOps endpoint for that network. --network takes any of a network's Substreams registry names, such as base or base-mainnet, or its CAIP-2 ID, such as eip155:8453.

Call RPC with curl

Your shell expands $GRAPHOPS_API_KEY before graphops starts, when the variable is not set yet. Wrap the request in sh -c '…' so the variable expands inside the command graphops exec runs:

CLI · GraphOps CLI

# sh -c expands $GRAPHOPS_API_KEY inside the command graphops runs, not in your shell.
graphops exec --product rpc -- sh -c '
  curl --fail-with-body --silent --show-error "https://rpc.graphops.xyz/v1/evm/1" \
    -H "Authorization: Bearer $GRAPHOPS_API_KEY" \
    -H "Content-Type: application/json" \
    --data "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"eth_blockNumber\", \"params\": []}"'

The response is the latest Ethereum block number as a hexadecimal quantity, such as {"jsonrpc":"2.0","id":1,"result":"0x193a60d"}. Replace 1 in the URL with another chain ID from Supported networks, and see RPC methods for what you can call.

Explore and query Subgraphs

Look at a published Subgraph's schema before you write a query against it. These commands use your sign-in, not your API key:

CLI · GraphOps CLI

# Find a published Subgraph, then read its schema and entities before you write a query.
graphops subgraphs browse --search uniswap --network mainnet
graphops subgraphs entities --subgraph-id <SUBGRAPH_ID>
graphops subgraphs schema --subgraph-id <SUBGRAPH_ID>

browse prints each Subgraph's Graph Network Subgraph ID and current Deployment CID. Pass either to entities, schema, manifest or metadata with --subgraph-id or --cid. Manage Subgraphs and Endpoint Aliases lists them all.

Then query it with your stored key:

CLI · GraphOps CLI

# GraphQL errors can arrive with HTTP 200: check the response for an "errors" array.
graphops exec --product subgraphs -- sh -c '
  curl --fail-with-body --silent --show-error "https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>" \
    -H "Authorization: Bearer $GRAPHOPS_API_KEY" \
    -H "Content-Type: application/json" \
    --data "{\"query\": \"{ _meta { deployment block { number } hasIndexingErrors } }\"}"'

_meta.block.number shows how far the deployment has indexed, and _meta.deployment which version answered. A Graph Network Subgraph ID follows each version its owner publishes; give a production application an Endpoint Alias instead. Identifier types explains the choice, and Query a Subgraph covers variables, errors and clients.

Iterate on your own Subgraph

From your Subgraph project, deploy each change to a Managed Subgraph and test it before it serves anything else:

CLI · GraphOps CLI

# From your Subgraph project: build with your Graph CLI and create the Managed Subgraph.
graphops subgraphs deploy my-subgraph --create
graphops subgraphs endpoint-aliases create my-subgraph-dev --managed-subgraph my-subgraph

# After each change: stage the new build as Next, wait until it can be promoted, then promote it.
graphops subgraphs deploy my-subgraph
graphops subgraphs wait my-subgraph --for promotable
graphops subgraphs promote my-subgraph

The first deploy creates the Managed Subgraph, and indexing and its charges start then. Each later deploy stages the build as the Next version while the Current version keeps serving, and the Endpoint Alias moves only when you promote. A Managed Subgraph needs a monthly plan. Deploy your own Subgraph walks through the first deploy, and Develop and release a Subgraph covers testing, rollback and releasing from CI.

Stream and sink Substreams

graphops substreams run reads the package's network, adds the GraphOps endpoint for it and gives your stored key to the Substreams CLI. graphops substreams sink protojson writes the same output to JSONL files:

CLI · GraphOps CLI

# The package's network selects the GraphOps endpoint; graphops adds the endpoint and your key.
graphops substreams run \
  "https://spkg.io/v1/packages/ethereum-common/v0.4.0" \
  "filtered_events" \
  --params "filtered_events=evt_addr:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 && evt_sig:0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" \
  --start-block 18000000 \
  --stop-block 18000010 \
  -o jsonl

# Write the same range to a JSONL file in ./output, one file per 10 blocks.
graphops substreams sink protojson \
  "https://spkg.io/v1/packages/ethereum-common/v0.4.0" \
  "filtered_events" \
  --params "filtered_events=evt_addr:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 && evt_sig:0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" \
  --start-block 18000000 \
  --stop-block 18000010 \
  --blocks-per-file 10

This streams the USDC Transfer events in ten Ethereum blocks with the pinned ethereum-common@v0.4.0 package, then writes them to ./output/0018000000-0018000010.jsonl. The sink saves its cursor in ./state.yaml, so running it again continues after the last block it wrote. Delete state.yaml to start over.

graphops substreams sink also runs the noop and webhook sinks. Run any other sink, such as the Postgres sink, through graphops exec, and use graphops substreams env to export the endpoint and key for a tool that reads them from your shell. Run Substreams with the GraphOps CLI shows both.

Next steps

Last updated