Skip to content

CLI release notes

What changed in each GraphOps CLI release, with the changes that need action in your scripts listed first.

Check these notes before you update the GraphOps CLI. graphops --version shows the version you have, and Update or remove the CLI shows how to update.

The CLI is in its 0.x series. A minor release, such as 0.3.0, can change commands, options, JSON output, error codes and exit codes, and lists each of those changes under Breaking. A patch release, such as 0.2.1, does not. In CI, install an exact version, for example npm install --global @graphops/cli@0.2.0, and read the notes before you move to the next minor release. Expect the next minor release to change the JSON output of most commands.

0.2.0

Breaking

  • -o json (--output json) replaces --json. Put it before or after the command, as in graphops subgraphs list -o json.
  • Every JSON error document has a code and says whether to retry: {"error": {"code", "message", "retryable"}}. Errors that had "code": null, such as not signed in, a network failure, an unexpected API response, a subgraphs wait timeout or a refused graph deploy argument, now carry a code from the error code table. A platform error with status 500 or higher keeps the platform's code instead of null, and so does a 401. With -o json, the npm package's own failures print the same document, with launch_failed, instead of a message on stderr.
  • retryable is true for network failures, request timeouts and 429, 502, 503 and 504 answers. Retry only those.
  • An organization you are not a member of exits 5 with organization_permission_insufficient whether you name it by slug or by ID, in every command and in graphops orgs use, instead of 2.
  • graphops auth login --with-token exits 2 with stdin_unreadable when it cannot read stdin, instead of 1.
  • graphops auth status -o json reports a service account in principal, with "kind": "service_account", instead of serviceAccount, and every document has valid and principal. A service account API key that GraphOps does not accept, such as a revoked one, is reported with valid false and exit 0 instead of exit 3. Use --check to fail on it.
  • --secret-file <file> replaces --output <file> for writing a new key's secret to a file, on api-keys create, api-keys rotate and service-accounts keys create.
  • graphops service-accounts update takes --add-grant <permission> and --remove-grant <permission> to change one permission, or --grants <file> to replace them all. --grant is gone: it replaced every permission, so following a permission error's advice could remove an account's other permissions.
  • graphops auth status -o json reports expiresAt as an RFC 3339 time instead of seconds.
  • The CLI stores one API key per organization, covering every data service the key was granted, instead of one key per data service. graphops api-keys create --store, api-keys store, api-keys current and api-keys forget replace graphops rpc key, graphops subgraphs key and graphops substreams key, which are gone. api-keys create --store grants every data service your organization can use unless you pass --product or --grants. api-keys store checks the key with GraphOps and needs a sign-in. Keys stored by 0.1.0 are no longer used: store a key again with graphops api-keys create --store or graphops api-keys store, and delete the old entries with graphops api-keys forget --all.
  • GRAPHOPS_API_KEY replaces GRAPHOPS_RPC_API_KEY, GRAPHOPS_SUBGRAPHS_API_KEY and GRAPHOPS_SUBSTREAMS_API_KEY, which the CLI no longer reads.
  • graphops exec sets GRAPHOPS_API_KEY, the variable the GraphOps code examples read, instead of one variable per data service, and SUBSTREAMS_API_KEY when the key covers Substreams. --product is optional: when you pass it, graphops exec checks that the stored key covers that data service and exits 125 (key_missing_product) without running your command if it doesn't.
  • graphops exec exits 125 when it fails before running your command, for example because a key is missing (missing_key), and 126 when your command can't run, instead of 2 or 4. Your command's own exit codes pass through unchanged.
  • graphops substreams run, gui and sink exit 125 when they fail before running the Substreams CLI, for example because the key is missing, an argument is refused or GraphOps does not serve the network, 126 when the Substreams CLI can't run and 127 when it isn't found, instead of 1, 2 or 4. The Substreams CLI's own exit codes pass through unchanged, so a script or process supervisor can tell the two apart.
  • graphops substreams packages list --network with a network GraphOps doesn't serve exits 2 (unsupported_network) and lists the supported names, instead of listing no packages.
  • The npm package exits 120 instead of 1 when it can't start graphops: on a system without a build, such as Alpine Linux, or when the package for your platform isn't installed.
  • graphops exec --product substreams no longer passes Substreams endpoint and credential variables from your shell, such as SUBSTREAMS_ENDPOINT or SINK_SQL_RUN_ENDPOINT, to your command. It points every network GraphOps serves at its GraphOps endpoint instead, and names the variables it removed.
  • graphops usage durations count whole periods, including the current one: usage daily --from 7d is today and the 6 days before.
  • A service account needs apiKeys.read as well as apiKeys.revoke to revoke a key, and as well as apiKeys.rename to rename one.
  • graphops api-keys update that removes a product or changes a limit needs --confirm with the key's name or ID, and so does graphops service-accounts update --grants that removes a permission or changes a limit, with the account's name or ID. Without it they exit 2 with confirmation_required and change nothing.
  • graphops api-keys show lists each product on its own line with its limits, after Products:, instead of marking it (limited) and adding a Managed Subgraphs: line.
  • The api-keys commands refuse a value that starts like a secret (gqk_ or gsk_) but is not a key ID with api_key_unknown (exit 2), without repeating it.
  • A command that changes something, run by a person with an organization ID configured, first checks that ID against their organizations, and exits 2 when they are not a member of it.
  • Homebrew installs the CLI as graphops/tap/graphops-cli. brew upgrade moves an existing graphops installation to the new name.
  • graphops subgraphs deploy, create and status JSON reports currentQueryUrl and nextQueryUrl (null without a Next version) instead of queryUrl. create also reports deploymentCid.
  • graphops subgraphs status, wait, promote, unstage, rename, target-type and delete JSON names each Deployment CID deploymentCid, as deploy and history do, instead of deploymentHash.
  • graphops subgraphs list JSON reports promotion, with the same eligible, state and reason as status, instead of upgradeState. The UPGRADE column is now PROMOTION.
  • graphops subgraphs deploy stops before building when a Next version is already staged and you didn't pass --replace-next (next_occupied), including when the build turns out to be the staged version. With --replace-next, a build of the staged version still changes nothing (already_staged).

Added

  • At a terminal, the CLI asks for what a command leaves out instead of failing. See Interactive use. Without a person at the terminal it never prompts: scripts, CI and coding agents get usage errors, exit codes and error codes as described here.

    • A missing Managed Subgraph, Endpoint Alias, API key, service account or organization is chosen from a list of your organization's. graphops subgraphs deploy without a name can also create a Managed Subgraph, and graphops subgraphs explore, metadata, schema, entities and manifest without --cid or --subgraph-id inspect the current version of a Managed Subgraph you choose. graphops api-keys create without --product asks for the data services. A Substreams run whose manifest's network cannot be read asks for the network.
    • A removal without --confirm, and an api-keys update or service-accounts update --grants that removes access, shows the plan and asks you to type the name. graphops aliases retarget and graphops subgraphs promote (without --expect-next) show the plan and ask yes or no, default no.
    • Errors offer their fix: sign in, create and store an API key for graphops exec and the Substreams commands, replace a staged Next version on deploy, or wait for a version before retargeting an Endpoint Alias to it.
    • After subgraphs create or a deploy that creates a Managed Subgraph, the CLI offers an Endpoint Alias; after a deploy stages a Next version, it offers to wait until it can be promoted; after subgraphs wait --for promotable, it offers the promotion, default no.
    • After a prompted run, Next time: <command> on stderr shows the full command.
  • graphops init sets up a new machine at a terminal: sign in, choose the organization, create and store an API key, install the agent skills and run graphops doctor. Without a terminal it exits 2 and lists those commands.

  • --no-input, before or after the command, and GRAPHOPS_NO_INPUT turn prompts off. The CLI also never prompts with -o json, under a coding agent or CI system it detects, or with TERM=dumb.

  • graphops doctor adds an interactive check that says whether the CLI may prompt, and why not.

  • Exit code 130 and error code cancelled: you cancelled at a prompt, and nothing changed.

  • graphops subgraphs history lists the versions a Managed Subgraph has served, and graphops subgraphs status shows the previous version.

  • graphops subgraphs deploy, create and status print the network and the query URL of the Current version, which stops working when a newer version is promoted, and of a staged Next version, for testing before promotion. They recommend an Endpoint Alias for applications, with the graphops aliases create command. graphops aliases create, show and list print each Endpoint Alias's query URL.

  • graphops subgraphs promote names the Endpoint Aliases that now serve the new version, says that the previous version's query URL stops working and how to roll back. JSON adds servingAliases.

  • graphops subgraphs deploy --create says which command creates the Subgraphs API key that querying needs.

  • graphops subgraphs status and list show the promotion state as Not staged, Indexing, Ready to promote or Blocked, and a version with no status yet as Waiting for indexing data.

  • graphops aliases commands name a Managed Subgraph target by its name. JSON adds managedSubgraphName.

  • graphops subgraphs wait reports a timeout with error.code wait_timeout, and graphops subgraphs deploy reports a refused Graph CLI argument with argument_refused.

  • graphops auth status shows who is signed in and the organization's name, and says when the session has expired or could not be checked. JSON adds principal and valid.

  • graphops auth status --check exits 0 only when a session or GRAPHOPS_TOKEN is present and GraphOps accepts it. Otherwise it exits 3 with not_signed_in, session_expired, credential_rejected or unverified, so CI can check its credential in one step.

  • -o, --profile and --organization work after the command, as in graphops subgraphs list -o json, as well as before it. After graphops substreams run, gui and sink, every argument still goes to the Substreams CLI, and from the command graphops exec runs onward, every argument goes to that command.

  • The CLI page and the command reference list every error code the CLI raises, with its exit code.

  • graphops usage accepts a UTC date, today, yesterday and --from month, and marks periods that are still in progress.

  • graphops usage and graphops credits ledger say what consumed credits: usage --by-attribution and usage windows name each row's API key and Managed Subgraph or Endpoint Alias and total the credits per key and per resource, and each ledger charge names its data service, API key, resource and usage window. Output is a table with a header, in UTC, with amounts grouped by thousands. --api-key also takes a key's name.

  • graphops agent-skills check also reports newly published skills, with the command to install them.

  • graphops substreams env prints the same variables graphops exec --product substreams sets, with unset lines for endpoint variables your shell already has.

  • Every command that changes something names the organization it acted in, such as in Acme (acme), and so does a --confirm that doesn't match.

  • The api-keys commands take a key's name as well as its ID, and --confirm accepts either. When several keys share the name, the command exits 2 with api_key_ambiguous and lists their IDs.

  • graphops api-keys revoke and rotate name the key, its products with their limits or its service account, and when it was last used.

  • graphops api-keys update and graphops service-accounts update --grants print the products or permissions they added and removed and the limits they changed. JSON adds added, removed and limitsChanged.

  • graphops api-keys create --like <key> creates a key with another key's products and limits, so you can replace a key without downtime: create its replacement, deploy the new secret, then revoke the old key.

  • graphops usage --from period starts at your current billing period, which follows your plan's renewal date; --from month is the calendar month in UTC.

  • graphops substreams run, gui and sink print the network and endpoint they stream from, and whether the network came from --network or the manifest, or defaulted to mainnet.

  • Every --network option of the Substreams commands and graphops exec takes any of a network's Substreams registry names, such as base or base-mainnet, or its CAIP-2 ID, such as eip155:8453.

  • graphops exec takes your command with or without a -- before it, so it works in PowerShell, which can drop the --.

  • The CLI trusts the certificate authorities in your operating system's trust store, as well as the public ones it includes, so it works behind a proxy that inspects TLS once the proxy's root certificate is installed. SSL_CERT_FILE and SSL_CERT_DIR name certificates to trust instead of the operating system's.

  • graphops api-keys create --store and graphops api-keys rotate --store store the new key as your organization's key without printing it. Rotating or revoking the stored key another way warns that it no longer works.

  • graphops doctor checks your organization's stored key with GraphOps: that it is still active and which data services it has. It names the variables graphops exec sets.

Fixed

  • graphops aliases retarget and graphops aliases update refuse to point an Endpoint Alias at a Managed Subgraph version that is not synced and healthy, unless you pass --force. For the next behavior they check the staged Next version, and retarget prints the old and new target.
  • graphops subgraphs list shows each Managed Subgraph's status and hides those being deleted.
  • graphops subgraphs wait stops at once when the Managed Subgraph is suspended or deleted.
  • graphops subgraphs promote lets GraphOps decide whether a promotion may proceed.
  • graphops subgraphs deploy refuses a Managed Subgraph that doesn't exist, and a Graph CLI --network other than the Managed Subgraph's, before it builds.
  • Service account and API key limits accept and show Managed Subgraph names.
  • Revoking a key that is already revoked, and graphops auth logout when you're signed out, say that nothing changed.
  • A --confirm value that doesn't match names the resource to repeat instead of printing it.
  • graphops api-keys current shows the same last four characters as the platform.
  • graphops service-accounts update --add-grant and --remove-grant show each permission with its limits, and say when a permission you add is already held and keeps its limits.
  • graphops service-accounts update --grant names --add-grant and --remove-grant instead of suggesting --grants, which replaces every permission.
  • When a new key's secret can't be written to its file, the advice names the revoke command without a --confirm value to copy.
  • When no organization is selected, the error also offers --organization <slug> for one command.
  • graphops substreams packages list --network base lists packages tagged base-mainnet too.
  • graphops substreams run, gui and sink accept an option value that starts with -, such as --cursor -Xq9e2Ldw_kA, instead of refusing it as an endpoint option.
  • graphops substreams sink webhook without a URL first says to pass the URL, instead of reading the manifest as the URL.
  • On Alpine and other musl-based Linux, the npm package says there is no build for it and to use a glibc-based Linux, instead of asking you to reinstall.
  • On Windows, graphops exec runs a command given as a path without an extension, such as .\node_modules\.bin\vite, and finds a command whose name contains a dot.
  • An empty GRAPHOPS_TOKEN is reported as empty instead of "not signed in", and without a terminal the sign-in advice also names GRAPHOPS_TOKEN.
  • graphops doctor as a service account no longer checks device sign-in, and suggests GRAPHOPS_API_KEY or graphops api-keys store instead of creating a key, which service accounts cannot do.
  • Stored keys belong to an organization. After graphops orgs use or with --organization, commands use that organization's key, and a missing key says which organization has none. Before, graphops exec kept using, and billing, the key stored for the previous organization.

0.1.0

First release.

Last updated