Skip to content

GraphOps CLI

Install the GraphOps CLI to deploy Managed Subgraphs, run Substreams, manage keys and Endpoint Aliases, and read usage and billing from your terminal, signed in to your organization.

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

TaskCommandsGuide
Deploy a Subgraph and release new versionsgraphops subgraphs deploy, wait, promote, status, historyDeploy with the GraphOps CLI
Rename a Managed Subgraph, change its Target type or delete itgraphops subgraphs rename, target-type, deleteManage Managed Subgraphs and Endpoint Aliases
Give applications a stable query URLgraphops aliasesManage Managed Subgraphs and Endpoint Aliases
Explore published Subgraphsgraphops subgraphs browse, explore, schema, entities, manifest, metadataExplore Subgraphs and Substreams packages
Stream Substreams with your organization's keygraphops substreams run, gui, sink, env, keyRun Substreams with the GraphOps CLI
Find Substreams packagesgraphops substreams packagesExplore Subgraphs and Substreams packages
See your organization, usage, credits and billinggraphops orgs show, usage, credits, billingCheck usage, credits and billing
Create, rotate and revoke API keysgraphops api-keysManage API keys and service accounts
Create service accounts and their keysgraphops service-accountsManage API keys and service accounts
Run your own code with a stored keygraphops rpc key, subgraphs key, execRun code with your keys
Set up a coding agentgraphops agent-skillsUse the CLI with a coding agent
Check your setupgraphops doctorFix 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 list lists your Managed Subgraphs with their status, such as Syncing (1200 blocks behind) or Suspended (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-cid stops 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 with graphops subgraphs unstage and 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). --behavior sets what it follows: current or next for a Managed Subgraph, latest-available or latest for a Graph Network Subgraph ID.
  • graphops aliases create, show and list print each alias's query URL, the address your application queries.
  • graphops aliases retarget points an alias at another target, and graphops aliases update changes its behavior. Applications using the alias's URL switch at once. retarget prints 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 browse pages through published Subgraphs; --search and --network narrow them.
  • For a Graph Network Subgraph ID (--subgraph-id), a Deployment CID (--cid) or both, graphops subgraphs explore summarizes the manifest, schema prints the GraphQL schema, entities lists entities and their fields, manifest prints the manifest, and metadata shows the network and start block.
  • graphops substreams packages list lists 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 show summarizes your organization: plan, available credits, active API keys and service access. graphops orgs products lists its data services.
  • graphops usage daily --from 30d shows credits consumed per day, today and the 29 days before; usage hourly covers up to 90 days and usage windows lists the usage records billing settles. Each line shows whether its period has elapsed or is in progress.
  • --from and --to take a UTC timestamp such as 2026-11-01T00:00:00Z, a UTC date such as 2026-11-01, today or yesterday, or month for the start of this month (--from only). A date in --to includes that whole day. A duration counts whole days or hours, the current one included: usage daily --from 7d is today and the 6 days before, and usage hourly --from 24h is this hour and the 23 before.
  • Filter by --product (rpc, subgraphs or substreams), --api-key with an API key ID such as gqk_0123456789abcdef01234567, or resource.
  • graphops credits show and credits ledger show your balance and its entries.
  • graphops billing show shows your plan, invoices and top-ups; billing top-ups, billing notifications and billing catalog list 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 --reveal to 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-grant removes one; the command prints every permission the account then holds. To replace them all, pass --grants <file> with the full list. In a --grants file, 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:

  1. graphops rpc key create creates an RPC key for your organization and stores it in your credential store without printing it. graphops subgraphs key create and graphops substreams key create do the same for Subgraphs and Substreams. To store a key you already have, pipe it to graphops rpc key set.
  2. graphops exec --product rpc -- node index.js runs your command with the key in GRAPHOPS_RPC_API_KEY, and in no other process. Repeat --product for code that uses several services. Substreams keys are also set as SUBSTREAMS_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 install installs the GraphOps agent skills for the coding agents it finds on your machine, such as Claude Code, Codex and Cursor. Pass --agent to choose, or --project to install them in the current project. Each download is checked against the checksum the GraphOps docs publish.
  • graphops agent-skills check exits 1 when an installed skill is out of date or GraphOps has published a new skill. graphops agent-skills update refreshes your skills and, for a new one, prints the graphops agent-skills install command that adds it. graphops agent-skills remove removes the skills it installed and never touches others.
  • Set GRAPHOPS_AGENT to a short name for the agent, such as claude-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

VariableEffect
GRAPHOPS_TOKENA service account API key (gsk_…). The CLI acts as that service account instead of your sign-in.
GRAPHOPS_ORGANIZATIONOrganization 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_KEYA data service key for this command, instead of the stored one. It is never stored.
GRAPHOPS_CONFIG_DIRConfiguration 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_BINPath of the graph or substreams binary to run, instead of the one the CLI finds.
GRAPHOPS_AGENTA short name for the coding agent running the CLI, up to 64 letters, digits, ., _ or -. Requests are marked as made by that agent.
NO_COLORTurns 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

CodeMeaning
0Success
1Failure, 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
2Invalid command, a refused argument or an unsupported network
3Not signed in, the sign-in expired or needs to be recent, or the service account API key was not accepted
4No stored key for the data service
5GraphOps refused the operation; the JSON error.code names the reason
6graphops subgraphs wait timed out
125graphops exec failed before running your command, for example because a key is missing
126graphops exec found your command but could not run it, for example because it is not executable
127graph, 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.

  1. Run the command from your Subgraph project, or install Graph CLI in it.
  2. Install the Substreams CLI and check that substreams --version works.
  3. To use a binary elsewhere, set GRAPHOPS_GRAPH_BIN or GRAPHOPS_SUBSTREAMS_BIN to 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.

  1. Remove the argument. graphops adds the endpoint for you.
  2. To use another endpoint or Graph Node, run graph or substreams directly.

Sign in again to continue

Creating a key needs a sign-in from the last 12 hours.

  1. Run graphops auth login, then run the command again.
  2. If GRAPHOPS_TOKEN is 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