Deploy Subgraphs to GraphOps and run Substreams from the terminal you already build in. The
GraphOps CLI, graphops, runs your own Graph CLI (graph) and Substreams CLI (substreams), and
adds GraphOps sign-in, your organization and its credentials. Your projects, arguments and tool
versions stay yours.
Install
Install with npm on macOS, Linux and Windows. The package needs Node.js 18 or newer.
CLI · GraphOps CLI
npm install --global @graphops/cli
Or install with Homebrew on macOS and Linux:
CLI · GraphOps CLI
brew install graphops/tap/graphops-cli
Both install the same graphops binary for macOS (Apple silicon and Intel), Linux (x86_64 and
arm64, glibc 2.34 or newer) and Windows (x86_64). The macOS binaries are signed and notarized by
GraphOps. The Windows binary is not code-signed yet, so Windows can warn about a copy you download
with a browser.
graphops does not install the tools it runs. Add Graph CLI to your Subgraph project
(npm install --save-dev @graphprotocol/graph-cli) and
install the Substreams CLI(opens in a new tab).
graphops doctor warns when a tool's version is outside the range GraphOps has tested.
Sign in and choose an organization
CLI · GraphOps CLI
# Approve the sign-in in your browser, then pick the organization to work in.
graphops auth login --open
graphops orgs list
graphops orgs use my-organization
# Check the configuration, sign-in, credentials and the graph and substreams tools.
graphops doctor
graphops auth login shows a code that you approve in your browser. graphops auth status shows
who is signed in and in which organization, and tells you when the session has expired.
Sign in to the CLI explains what you approve and how to end the session.
Commands then act in the organization you chose, with your role in it. To use another
organization for one command, pass --organization with its slug or ID.
The CLI keeps your session and stored API keys in your operating system's credential store: the
macOS Keychain, the Secret Service on Linux, or Windows Credential Manager. Where none is available,
such as a Linux server without a desktop session or an SSH session on Windows, it keeps them 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. 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.
What you can do
| Task | Commands | Guide |
|---|---|---|
| Deploy a Subgraph and release new versions | graphops subgraphs deploy, wait, promote, status, history | Deploy with the GraphOps CLI |
| Rename a Managed Subgraph, change its Target type or delete it | graphops subgraphs rename, target-type, delete | Manage Managed Subgraphs and Endpoint Aliases |
| Give applications a stable query URL | graphops aliases | Manage Managed Subgraphs and Endpoint Aliases |
| Explore published Subgraphs | graphops subgraphs browse, explore, schema, entities, manifest, metadata | Explore Subgraphs and Substreams packages |
| Stream Substreams with your organization's key | graphops substreams run, gui, sink, env, key | Run Substreams with the GraphOps CLI |
| Find Substreams packages | graphops substreams packages | Explore Subgraphs and Substreams packages |
| See your organization, usage, credits and billing | graphops orgs show, usage, credits, billing | Check usage, credits and billing |
| Create, rotate and revoke API keys | graphops api-keys | Manage API keys and service accounts |
| Create service accounts and their keys | graphops service-accounts | Manage API keys and service accounts |
| Run your own code with a stored key | graphops rpc key, subgraphs key, exec | Run code with your keys |
| Set up a coding agent | graphops agent-skills | Use the CLI with a coding agent |
| Check your setup | graphops doctor | Fix common problems |
graphops --help and graphops <command> --help list every command and option. For scripts, add
-o json (--output json) before the command, as in graphops -o json subgraphs list, to get one
JSON document on standard output. Messages go to standard error. graphops exec and
graphops substreams run, gui and sink print the output of the command they run, so they
refuse -o json.
Manage Managed Subgraphs and Endpoint Aliases
graphops subgraphs listlists your Managed Subgraphs with their status, such asSyncing (1200 blocks behind)orSuspended (credits exhausted). Those being deleted appear only with--all.graphops subgraphs rename <name> <new-name>renames a Managed Subgraph.graphops subgraphs target-type <name> --subgraph-id <id>makes it follow a Graph Network Subgraph ID, so new versions are staged and promoted for you.--current-cidstops following and keeps the current Deployment CID.graphops subgraphs delete <name> --confirm <name>deletes it: indexing stops and so does its billing. Cancel a staged upgrade withgraphops subgraphs unstageand remove its Endpoint Aliases first.graphops aliases create <alias>creates an Endpoint Alias for a Deployment CID (--cid), a Managed Subgraph (--managed-subgraph) or a Graph Network Subgraph ID (--subgraph-id).--behaviorsets what it follows:currentornextfor a Managed Subgraph,latest-availableorlatestfor a Graph Network Subgraph ID.graphops aliases create,showandlistprint each alias's query URL, the address your application queries.graphops aliases retargetpoints an alias at another target, andgraphops aliases updatechanges its behavior. Applications using the alias's URL switch at once.retargetprints the old and new target, and refuses a Managed Subgraph that is not yet synced and healthy unless you pass--force.graphops aliases delete <alias> --confirm <alias>deletes it, and its URL stops working.
Identifiers and Endpoint Aliases explains which identifier an application should query.
Explore Subgraphs and Substreams packages
graphops subgraphs browsepages through published Subgraphs;--searchand--networknarrow them.- For a Graph Network Subgraph ID (
--subgraph-id), a Deployment CID (--cid) or both,graphops subgraphs exploresummarizes the manifest,schemaprints the GraphQL schema,entitieslists entities and their fields,manifestprints the manifest, andmetadatashows the network and start block. graphops substreams packages listlists popular packages per network, without signing in.graphops substreams packages show <slug> <version>shows a package's modules and outputs.
Check usage, credits and billing
graphops orgs showsummarizes your organization: plan, available credits, active API keys and service access.graphops orgs productslists its data services.graphops usage daily --from 30dshows credits consumed per day, today and the 29 days before;usage hourlycovers up to 90 days andusage windowslists the usage records billing settles. Each line shows whether its period haselapsedor isin progress.--fromand--totake a UTC timestamp such as2026-11-01T00:00:00Z, a UTC date such as2026-11-01,todayoryesterday, ormonthfor the start of this month (--fromonly). A date in--toincludes that whole day. A duration counts whole days or hours, the current one included:usage daily --from 7dis today and the 6 days before, andusage hourly --from 24his this hour and the 23 before.- Filter by
--product(rpc,subgraphsorsubstreams),--api-keywith an API key ID such asgqk_0123456789abcdef01234567, or resource. graphops credits showandcredits ledgershow your balance and its entries.graphops billing showshows your plan, invoices and top-ups;billing top-ups,billing notificationsandbilling cataloglist orders, notification settings and prices.
These commands only read. Change your plan, buy credits and manage payment in Billing; see Billing and credits.
Manage API keys and service accounts
graphops api-keys lists, creates, changes, renames, rotates and revokes your organization's
API keys. graphops service-accounts creates
service accounts, changes their
permissions, deletes them, and creates their keys. Run a command with --help to see its options.
- A new key's secret is shown once. Pass
--revealto print it, alone on its line, so you can pipe it straight into your CI system's secret store. Or pass--secret-file <file>to write it to a new file that only you can read. The command requires one of the two. - Changing a service account's permissions keeps the others.
graphops service-accounts update <account> --add-grant <permission>adds a permission and--remove-grantremoves one; the command prints every permission the account then holds. To replace them all, pass--grants <file>with the full list. In a--grantsfile, for service accounts or query keys, limit a permission to Managed Subgraphs by name or ID. - Rotating, revoking and deleting ask you to confirm. Repeat the key's ID, or the service
account's name or ID, with
--confirm. A rotated key stops working at once. Deleting a Managed Subgraph or an Endpoint Alias asks for its name in the same way. - Creating and changing credentials needs a recent sign-in. If the CLI asks you to sign in
again, run
graphops auth login.
Run code with your keys
Store a key for a data service once, then run your code with it:
graphops rpc key createcreates an RPC key for your organization and stores it in your credential store without printing it.graphops subgraphs key createandgraphops substreams key createdo the same for Subgraphs and Substreams. To store a key you already have, pipe it tographops rpc key set.graphops exec --product rpc -- node index.jsruns your command with the key inGRAPHOPS_RPC_API_KEY, and in no other process. Repeat--productfor code that uses several services. Substreams keys are also set asSUBSTREAMS_API_KEY.
Your command's output and exit code are its own. The key stays out of your shell history and your shell's environment, but anything your code prints, including its environment, can show it.
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. Add --network <network> to
set SUBSTREAMS_ENDPOINT to the GraphOps endpoint for that network.
Run Substreams with the GraphOps CLI shows a
sink run this way.
graphops rpc key show reports the key your commands use. When GRAPHOPS_RPC_API_KEY is set, that
is the variable's key, not the stored one.
Use the CLI with a coding agent
A coding agent can use the CLI as you: you approve its sign-in in your browser, your role applies,
and stored keys reach its code through graphops exec without appearing in its transcript.
graphops agent-skills installinstalls the GraphOps agent skills for the coding agents it finds on your machine, such as Claude Code, Codex and Cursor. Pass--agentto choose, or--projectto install them in the current project. Each download is checked against the checksum the GraphOps docs publish.graphops agent-skills checkexits1when an installed skill is out of date or GraphOps has published a new skill.graphops agent-skills updaterefreshes your skills and, for a new one, prints thegraphops agent-skills installcommand that adds it.graphops agent-skills removeremoves the skills it installed and never touches others.- Set
GRAPHOPS_AGENTto a short name for the agent, such asclaude-code, so its requests are marked as made by an agent.
Use GraphOps with AI agents covers the skills and the docs MCP server.
Run the CLI in CI
Automation signs in as a service account, not as a person. Store one
of the account's service account API keys as a secret of your CI system and set it as
GRAPHOPS_TOKEN in the job that runs graphops. Never pass the key as an argument. The CLI then
acts in the account's organization, with the account's permissions, and never stores the key.
Commands that act as a person do not run as a service account: auth login, auth logout,
auth token, orgs list, orgs use, the key create commands, and the api-keys and
service-accounts commands that create or change credentials. The Subgraphs guide lists the
permissions a release needs.
Environment variables
| Variable | Effect |
|---|---|
GRAPHOPS_TOKEN | A service account API key (gsk_…). The CLI acts as that service account instead of your sign-in. |
GRAPHOPS_ORGANIZATION | Organization slug or ID for this command. A service account accepts only its own organization ID. |
GRAPHOPS_RPC_API_KEY, GRAPHOPS_SUBGRAPHS_API_KEY, GRAPHOPS_SUBSTREAMS_API_KEY | A data service key for this command, instead of the stored one. It is never stored. |
GRAPHOPS_CONFIG_DIR | Configuration directory. The default is ~/.config/graphops (or $XDG_CONFIG_HOME/graphops) on macOS and Linux and %APPDATA%\graphops on Windows. |
GRAPHOPS_GRAPH_BIN, GRAPHOPS_SUBSTREAMS_BIN | Path of the graph or substreams binary to run, instead of the one the CLI finds. |
GRAPHOPS_AGENT | A short name for the coding agent running the CLI, up to 64 letters, digits, ., _ or -. Requests are marked as made by that agent. |
NO_COLOR | Turns off colored output. |
The CLI ignores spaces and line breaks around GRAPHOPS_TOKEN and the key variables, so a value
saved with a trailing newline works.
The tools graphops runs never receive these variables. graphops exec sets only the key
variables you ask for with --product.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Failure, such as a network error or a tool that failed before deploying; graphops agent-skills check when a skill is out of date or new |
2 | Invalid command, a refused argument or an unsupported network |
3 | Not signed in, the sign-in expired or needs to be recent, or the service account API key was not accepted |
4 | No stored key for the data service |
5 | GraphOps refused the operation; the JSON error.code names the reason |
6 | graphops subgraphs wait timed out |
125 | graphops exec failed before running your command, for example because a key is missing |
126 | graphops exec found your command but could not run it, for example because it is not executable |
127 | graph, substreams or the command for graphops exec was not found |
graphops substreams run, gui and sink end with the Substreams CLI's own exit code.
graphops exec ends with your command's exit code. When graphops exec itself fails, it exits
125, 126 or 127 instead of 2 or 4, so your script can tell its failures from your
command's.
Fix common problems
Start with graphops doctor. It checks your configuration, sign-in, organization, credential
store, data service keys and the graph and substreams tools, prints one line per check with a fix
where there is one, and exits 1 when a check fails.
graph not found or substreams not found
The CLI could not find the tool it runs. It uses the nearest node_modules/.bin/graph above the
current directory, then graph on your PATH, and substreams on your PATH.
- Run the command from your Subgraph project, or install Graph CLI in it.
- Install the Substreams CLI and check that
substreams --versionworks. - To use a binary elsewhere, set
GRAPHOPS_GRAPH_BINorGRAPHOPS_SUBSTREAMS_BINto its path.
graphops refuses an argument
graphops sets the GraphOps endpoint and credentials itself, so it refuses arguments that would
send them elsewhere: --node, --deploy-key and --watch for graph deploy, and --endpoint,
--plaintext, --insecure, --api-key-envvar and --api-token-envvar for Substreams.
- Remove the argument.
graphopsadds the endpoint for you. - To use another endpoint or Graph Node, run
graphorsubstreamsdirectly.
Sign in again to continue
Creating a key needs a sign-in from the last 12 hours.
- Run
graphops auth login, then run the command again. - If
GRAPHOPS_TOKENis set, unset it first: it takes precedence over your sign-in.
Secrets are stored in secrets.toml
No credential store was available, so the CLI used the file instead. On a desktop, sign in to a
session with the Keychain, the Secret Service or Credential Manager available. On a server or in
CI, set GRAPHOPS_TOKEN and the data service key variables instead, which are never stored.
Update or remove the CLI
Update with npm install --global @graphops/cli@latest or brew upgrade graphops-cli. Before you
remove it, run graphops auth logout, which signs the CLI out and deletes its stored session. Stored
keys stay active until you revoke them, with graphops api-keys revoke or in
API keys. Then run npm uninstall --global @graphops/cli or
brew uninstall graphops-cli.
Next steps
Last updated