# Reference

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

Look up what an environment variable changes and what an exit code or error code means, so a script
can react to each failure correctly. For step-by-step fixes, see
[Troubleshooting](/platform/cli/troubleshooting).

## 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_API_KEY`                                   | An API key for this command, instead of your organization's stored key. It is never stored. `graphops exec` passes it to your command.                                                                |
| `GRAPHOPS_CONFIG_DIR`                                | Configuration directory. The default is `~/.config/graphops` (or `$XDG_CONFIG_HOME/graphops`) on macOS and Linux and `%APPDATA%\graphops` on Windows, which is `$env:APPDATA\graphops` in PowerShell. |
| `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, and the CLI never prompts.                                   |
| `GRAPHOPS_NO_INPUT`                                  | Any value turns prompts off, as `--no-input` does. See [Prompts at a terminal](/platform/cli#prompts-at-a-terminal).                                                                                  |
| `GRAPHOPS_UPDATE_REGISTRY_URL`                       | An npm registry mirror that `graphops self-update` and `graphops doctor` read the latest version from, instead of `https://registry.npmjs.org`. It must use HTTPS.                                    |
| `HTTPS_PROXY`, `ALL_PROXY`, `HTTP_PROXY`, `NO_PROXY` | The proxy for requests to GraphOps, and the hosts to reach without it. See [Requests fail behind a proxy](/platform/cli/troubleshooting#requests-fail-behind-a-proxy).                                |
| `SSL_CERT_FILE`, `SSL_CERT_DIR`                      | On Linux, certificate authorities to trust instead of the system bundle. See [Requests fail behind a proxy](/platform/cli/troubleshooting#requests-fail-behind-a-proxy).                              |
| `NO_COLOR`                                           | Turns off colored output.                                                                                                                                                                             |

The CLI ignores spaces and line breaks around `GRAPHOPS_TOKEN` and `GRAPHOPS_API_KEY`, so a value
saved with a trailing newline works. An empty `GRAPHOPS_TOKEN` counts as unset, and when the CLI
then finds no sign-in its error says that `GRAPHOPS_TOKEN` is empty.

To set a variable for the rest of your shell session, run `export NAME=value` on macOS and Linux,
`$env:NAME = 'value'` in PowerShell, or `set NAME=value` in Command Prompt. To unset it, run
`unset NAME`, `Remove-Item Env:NAME` or `set NAME=`.

The tools `graphops` runs never receive these variables. `graphops exec` sets only
`GRAPHOPS_API_KEY`, and `SUBSTREAMS_API_KEY` for Substreams.

## Exit codes

| Code  | Meaning                                                                                                                                                                                   |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`   | Success                                                                                                                                                                                   |
| `1`   | Failure, such as a network error, an error from GraphOps 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, an unsupported network, or `graphops self-update` of a copy it cannot update                                                                         |
| `3`   | Not signed in, the sign-in expired or needs to be recent, the service account API key was not accepted, or `graphops auth status --check` found no valid credential                       |
| `4`   | No API key for your organization, or the stored key does not cover the data service                                                                                                       |
| `5`   | GraphOps refused the operation, including an organization you are not a member of; the JSON `error.code` names the reason                                                                 |
| `6`   | `graphops subgraphs wait` timed out                                                                                                                                                       |
| `120` | The npm package could not start `graphops`: there is no build for your system, such as Alpine Linux, or the package for your platform is not installed                                    |
| `125` | `graphops exec`, or `graphops substreams run`, `gui` or `sink`, failed before running your command or the Substreams CLI, for example because a key is missing or an argument was refused |
| `126` | `graphops exec`, or `graphops substreams run`, `gui` or `sink`, found your command or the Substreams CLI but could not run it, for example because it is not executable                   |
| `127` | `graph`, `substreams`, the command for `graphops exec`, or the `npm` or `brew` that `graphops self-update` runs was not found                                                             |
| `130` | You cancelled at a prompt, with Ctrl+C or Esc, or answered no to a plan; nothing changed                                                                                                  |

`graphops exec` ends with your command's exit code, and `graphops substreams run`, `gui` and `sink`
end with the Substreams CLI's. When they fail themselves, they exit `125`, `126` or `127` instead
of `1`, `2` or `4`, so your script or process supervisor can tell their failures from those of the
program they run.

## Error codes

With `-o json`, a command that fails prints one document on standard output,
`{"error": {"code": "…", "message": "…", "retryable": false}}`. Act on `code`, which stays the same
for the same failure, and show `message` to people: its wording can change. `retryable` is `true`
when running the same command again can succeed: the network failed, a request timed out, or
GraphOps answered `429`, `502`, `503` or `504`. Wait before you retry, and wait longer after each
attempt.

Every error has a code. The CLI raises the codes below itself. Any other code comes from GraphOps
unchanged, and the [error reference](/platform/errors) explains it. The exit code shown is the
code's own. `graphops exec` and `graphops substreams run`, `gui` and `sink` exit `125` instead for
every code except `command_not_executable` (`126`) and `tool_not_found` (`127`), so
`argument_refused`, for example, exits `2` for `graphops subgraphs deploy` and `125` for
`graphops substreams run`.

| Code                                 | Exit code | Meaning                                                                                                                                                                                             |
| ------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `network_error`                      | `1`       | A request could not reach GraphOps or another service it needs. Retryable.                                                                                                                          |
| `request_timeout`                    | `1`       | A request timed out. Retryable.                                                                                                                                                                     |
| `platform_error`                     | `1`       | The platform answered with an error that carries no code. Retryable for 429, 502, 503 and 504.                                                                                                      |
| `unexpected_response`                | `1`       | A response the CLI cannot read, such as a record without a field it needs.                                                                                                                          |
| `request_invalid`                    | `1`       | The CLI could not build a request.                                                                                                                                                                  |
| `config_invalid`                     | `1`       | A file the CLI keeps in its configuration directory does not parse.                                                                                                                                 |
| `local_file_error`                   | `1`       | Reading, writing or locking a local file or directory failed.                                                                                                                                       |
| `directory_unknown`                  | `1`       | The configuration or home directory cannot be determined; the message names the variable to set.                                                                                                    |
| `secret_store_unavailable`           | `1`       | No OS credential store is available for this operation.                                                                                                                                             |
| `secret_store_failed`                | `1`       | The OS credential store or `secrets.toml` failed, holds a malformed entry, or is readable by other users.                                                                                           |
| `secret_lost`                        | `1`       | A key was created but its secret could not be written to `--secret-file`; revoke the key.                                                                                                           |
| `skills_unavailable`                 | `1`       | The GraphOps docs did not serve the agent skills index or a skill.                                                                                                                                  |
| `skill_invalid`                      | `1`       | The agent skills index is not valid, or names a skill served from another site.                                                                                                                     |
| `skill_digest_mismatch`              | `1`       | A downloaded agent skill does not match its published digest; nothing was written.                                                                                                                  |
| `graph_failed`                       | `1`       | `graph deploy` ended before GraphOps recorded the deploy.                                                                                                                                           |
| `bridge_failed`                      | `1`       | `subgraphs deploy` could not start the local endpoint it gives `graph deploy`.                                                                                                                      |
| `process_failed`                     | `1`       | The CLI could not wait for a wrapped tool.                                                                                                                                                          |
| `signal_handlers_failed`             | `1`       | The CLI could not install its signal handling around a wrapped tool.                                                                                                                                |
| `command_not_executable`             | `1`       | The command or wrapped tool exists but cannot start (exit 126 for `exec`).                                                                                                                          |
| `substreams_info_failed`             | `1`       | `substreams info` could not start.                                                                                                                                                                  |
| `revocation_failed`                  | `1`       | `auth logout` could not revoke the refresh token (a warning; the session is still removed).                                                                                                         |
| `usage`                              | `2`       | The arguments do not parse, or `graphops init` ran without a terminal.                                                                                                                              |
| `env_invalid`                        | `2`       | An environment variable is not valid UTF-8, or `GRAPHOPS_AGENT` is not 1 to 64 letters, digits, `.`, `_` or `-`.                                                                                    |
| `profile_invalid`                    | `2`       | The profile is not defined, or one of its URLs is not https.                                                                                                                                        |
| `json_unsupported`                   | `2`       | `-o json` on `exec`, `substreams run`, `substreams gui`, `substreams sink`, or `self-update` without `--check`.                                                                                     |
| `confirmation_mismatch`              | `2`       | `--confirm`, or the name typed at a confirmation prompt, does not match the resource.                                                                                                               |
| `confirmation_required`              | `2`       | A change that removes access, such as an `api-keys update` that removes a product or changes a limit, needs `--confirm`.                                                                            |
| `argument_refused`                   | `2`       | A `graph deploy` or Substreams argument that would change the endpoint, transport or credential, or a manifest on stdin (125 for `substreams run`, `gui` and `sink`).                               |
| `target_missing`                     | `2`       | No target given: an Endpoint Alias needs `--cid`, `--managed-subgraph` or `--subgraph-id`, a Subgraph lookup `--cid` or `--subgraph-id`.                                                            |
| `behavior_unsupported`               | `2`       | `--behavior` does not apply to the Endpoint Alias's target type.                                                                                                                                    |
| `time_invalid`                       | `2`       | A `usage` `--from` or `--to` that is not a time, date, word or duration the command takes.                                                                                                          |
| `no_billing_period`                  | `2`       | `usage --from period` for an organization without a current billing period.                                                                                                                         |
| `timeout_invalid`                    | `2`       | A `subgraphs wait --timeout` that is not `<n>s`, `<n>m` or `<n>h`, or is too large.                                                                                                                 |
| `grants_invalid`                     | `2`       | `--grants` cannot be read or is not a JSON array of grants.                                                                                                                                         |
| `grant_conflict`                     | `2`       | `--add-grant` and `--remove-grant` name the same permission.                                                                                                                                        |
| `grant_not_held`                     | `2`       | `--remove-grant` names a permission the service account does not hold.                                                                                                                              |
| `nothing_to_change`                  | `2`       | `service-accounts update` without a change.                                                                                                                                                         |
| `api_key_unknown`                    | `2`       | An API key name or ID that names no key of the organization, or a value shaped like a key's secret.                                                                                                 |
| `api_key_ambiguous`                  | `2`       | An API key name that several keys share; pass an ID.                                                                                                                                                |
| `like_not_query_key`                 | `2`       | `api-keys create --like` names a service account API key; it copies a query key.                                                                                                                    |
| `key_already_stored`                 | `2`       | `api-keys create --store` without `--replace` while a key is stored for the organization.                                                                                                           |
| `key_empty`                          | `2`       | `api-keys store` read no key from stdin.                                                                                                                                                            |
| `key_invalid`                        | `2`       | `api-keys store` read something that is not a query key (`gqk_…`) with a valid checksum.                                                                                                            |
| `token_empty`                        | `2`       | `auth login --with-token` read no token from stdin.                                                                                                                                                 |
| `stdin_unreadable`                   | `2`       | stdin could not be read.                                                                                                                                                                            |
| `secret_file_unusable`               | `2`       | The `--secret-file` cannot be created, for example because it exists.                                                                                                                               |
| `network_requires_substreams`        | `2`       | `exec --network` without a key that covers Substreams or `--product substreams`.                                                                                                                    |
| `command_missing`                    | `2`       | `exec` without a command after `--`.                                                                                                                                                                |
| `unsupported_network`                | `2`       | GraphOps does not serve Substreams for the network.                                                                                                                                                 |
| `network_repeated`                   | `2`       | `--network` given more than once.                                                                                                                                                                   |
| `network_missing`                    | `2`       | `--network` without a value.                                                                                                                                                                        |
| `network_undetermined`               | `2`       | No `--network`, and the manifest is not first or `substreams info` cannot read it.                                                                                                                  |
| `webhook_url_missing`                | `2`       | `substreams sink webhook` without the URL first.                                                                                                                                                    |
| `sink_unsupported`                   | `2`       | `substreams sink <kind>` for a kind other than `noop`, `protojson` or `webhook`.                                                                                                                    |
| `service_account_credential_invalid` | `2`       | `GRAPHOPS_TOKEN` starts with `gsk_` but is not a well-formed service account API key.                                                                                                               |
| `query_key_not_supported`            | `2`       | `GRAPHOPS_TOKEN` holds a query key (`gqk_`), which works only with data services.                                                                                                                   |
| `organization_not_selected`          | `2`       | No organization is configured and you are a member of several (or none).                                                                                                                            |
| `organization_mismatch`              | `2`       | The configured organization is not the service account's own organization ID.                                                                                                                       |
| `coding_agent_not_found`             | `2`       | `agent-skills install` found no coding agent; pass `--agent`.                                                                                                                                       |
| `skill_unknown`                      | `2`       | An agent skill name that GraphOps does not publish.                                                                                                                                                 |
| `self_update_unsupported`            | `2`       | `self-update` of a graphops that Homebrew or a global npm install did not install, such as a release archive, a build from source or a project's `node_modules`; the message says how to update it. |
| `not_signed_in`                      | `3`       | No session and no `GRAPHOPS_TOKEN`, or `GRAPHOPS_TOKEN` is set but empty.                                                                                                                           |
| `session_expired`                    | `3`       | The stored session expired and could not be refreshed, or the platform no longer accepts it.                                                                                                        |
| `session_invalid`                    | `3`       | The stored session is missing from the credential store or cannot be read.                                                                                                                          |
| `credential_rejected`                | `3`       | The platform did not accept the credential and sent no code of its own; for `auth status --check`, a `GRAPHOPS_TOKEN` it rejected.                                                                  |
| `unverified`                         | `3`       | `auth status --check` could not verify the credential, for example offline. Retryable when the cause is.                                                                                            |
| `id_token_missing`                   | `3`       | The session has no ID token, or a refresh returned none.                                                                                                                                            |
| `sign_in_unavailable`                | `3`       | Device sign-in is not available for this profile.                                                                                                                                                   |
| `sign_in_denied`                     | `3`       | The sign-in was denied in the browser.                                                                                                                                                              |
| `sign_in_expired`                    | `3`       | The sign-in code expired before it was approved.                                                                                                                                                    |
| `sign_in_failed`                     | `3`       | The sign-in server refused or ended the sign-in, or returned a session without an expiry.                                                                                                           |
| `session_required`                   | `3`       | A person-only command run with a service account credential.                                                                                                                                        |
| `missing_key`                        | `4`       | No `GRAPHOPS_API_KEY` and no stored API key for the selected organization, or the stored key's secret is missing (125 under `exec`).                                                                |
| `key_missing_product`                | `4`       | The stored API key does not cover a data service `exec --product` names, or Substreams for the Substreams commands (125 under `exec`).                                                              |
| `not_found`                          | `5`       | No Managed Subgraph, Endpoint Alias, API key or service account has that name or ID.                                                                                                                |
| `next_missing`                       | `5`       | The Managed Subgraph has no staged Next version.                                                                                                                                                    |
| `next_changed`                       | `5`       | The staged Next version is not the one `--expect-next` names.                                                                                                                                       |
| `next_occupied`                      | `5`       | A different Next version is staged; pass `--replace-next` to replace it.                                                                                                                            |
| `schema_incompatible`                | `5`       | The new version's schema removes or changes query definitions; pass `--accept-schema-changes`.                                                                                                      |
| `managed_subgraph_deleting`          | `5`       | The Managed Subgraph is being deleted.                                                                                                                                                              |
| `managed_subgraph_suspended`         | `5`       | The Managed Subgraph is suspended.                                                                                                                                                                  |
| `deployment_failed`                  | `5`       | The version `subgraphs wait` watches failed to index.                                                                                                                                               |
| `key_revoked`                        | `5`       | `api-keys store` of a revoked key.                                                                                                                                                                  |
| `no_data_services`                   | `5`       | `api-keys create --store` without products for an organization with no data services.                                                                                                               |
| `target_not_synced`                  | `5`       | The version an Endpoint Alias would serve is not synced and healthy; pass `--force` to change it anyway.                                                                                            |
| `wait_timeout`                       | `6`       | `subgraphs wait` timed out.                                                                                                                                                                         |
| `launch_failed`                      | `120`     | The npm package could not start graphops: no build for this system, such as musl Linux, or the platform package is not installed.                                                                   |
| `tool_not_found`                     | `127`     | The wrapped tool, or the command `exec` runs, is not found.                                                                                                                                         |
| `cancelled`                          | `130`     | A person cancelled at a prompt: Ctrl-C or Esc, or No to a plan. Only at a terminal.                                                                                                                 |

## Next steps

* [Troubleshooting](/platform/cli/troubleshooting): Fix the most common errors.
* [Scripts, CI and coding agents](/platform/cli/automation): Read JSON output and run the CLI in CI.
* [Error reference](/platform/errors): Look up an error code GraphOps returns.