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:
| System | Credential store |
|---|---|
| macOS | The login Keychain. macOS can ask you to allow graphops to read it. |
| Linux desktop | The Secret Service, such as GNOME Keyring or KWallet. |
| Windows | Windows 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 statusshows who is signed in, the organization commands act in, and which store holds your secrets:secret store: keychainfor the operating system's credential store, orsecret store: file <path>forsecrets.toml.graphops api-keys currentshows the key your commands use: its ID, name, data services and last four characters. WhenGRAPHOPS_API_KEYis set in your shell, it reports that variable's key instead, because the variable takes precedence over the stored key.--revealalso prints the secret.graphops doctorchecks your sign-in, organization, credential store, that the stored key is still active, and the variablesgraphops execsets. 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
execoptions 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 exits125without running it if not. The CLI cannot check a key you set inGRAPHOPS_API_KEY, so it runs your command with that key as given.- Your command's output and exit code are its own. When
graphops execfails before your command starts, for example because no key is stored, it exits125, 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