# GraphOps CLI

Source: https://docs.graphops.xyz/platform/cli

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.

```sh
npm install --global @graphops/cli

```

Or install with Homebrew on macOS and Linux:

```sh
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](https://docs.substreams.dev/how-to-guides/installing-the-cli).
`graphops doctor` warns when a tool's version is outside the range GraphOps has tested.

## Sign in and choose an organization

```sh
# 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](/platform/cli/sign-in) 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](/subgraphs/guides/deploy-with-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](#manage-managed-subgraphs-and-endpoint-aliases) |
| Give applications a stable query URL                           | `graphops aliases`                                                                   | [Manage Managed Subgraphs and Endpoint Aliases](#manage-managed-subgraphs-and-endpoint-aliases) |
| Explore published Subgraphs                                    | `graphops subgraphs browse`, `explore`, `schema`, `entities`, `manifest`, `metadata` | [Explore Subgraphs and Substreams packages](#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](/substreams/guides/run-with-graphops-cli)                |
| Find Substreams packages                                       | `graphops substreams packages`                                                       | [Explore Subgraphs and 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](#check-usage-credits-and-billing)                            |
| Create, rotate and revoke API keys                             | `graphops api-keys`                                                                  | [Manage API keys and service accounts](#manage-api-keys-and-service-accounts)                   |
| Create service accounts and their keys                         | `graphops service-accounts`                                                          | [Manage API keys and 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](#run-code-with-your-keys)                                             |
| Set up a coding agent                                          | `graphops agent-skills`                                                              | [Use the CLI with a coding agent](#use-the-cli-with-a-coding-agent)                             |
| Check your setup                                               | `graphops doctor`                                                                    | [Fix common problems](#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 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](/subgraphs/concepts/identifiers-and-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](/platform/billing-and-credits).

## Manage API keys and service accounts

`graphops api-keys` lists, creates, changes, renames, rotates and revokes your organization's
[API keys](/platform/api-keys). `graphops service-accounts` creates
[service accounts](/platform/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](/substreams/guides/run-with-graphops-cli#run-a-sink) 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](/ai-agents) covers the skills and the docs MCP server.

## Run the CLI in CI

Automation signs in as a [service account](/platform/service-accounts), 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](/subgraphs/guides/deploy-with-graphops-cli#release-from-ci).

## 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`.

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

* [Deploy with the GraphOps CLI](/subgraphs/guides/deploy-with-graphops-cli): Create a Managed Subgraph from your project and release new versions.
* [Run Substreams with the GraphOps CLI](/substreams/guides/run-with-graphops-cli): Stream a package with your organization's Substreams key.
* [Sign in to the CLI](/platform/cli/sign-in): Check what you approve and end a CLI session.