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 ingraphops 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, asubgraphs waittimeout or a refusedgraph deployargument, now carry a code from the error code table. A platform error with status500or higher keeps the platform's code instead ofnull, and so does a401. With-o json, the npm package's own failures print the same document, withlaunch_failed, instead of a message on stderr. retryableistruefor network failures, request timeouts and429,502,503and504answers. Retry only those.- An organization you are not a member of exits
5withorganization_permission_insufficientwhether you name it by slug or by ID, in every command and ingraphops orgs use, instead of2. graphops auth login --with-tokenexits2withstdin_unreadablewhen it cannot read stdin, instead of1.graphops auth status -o jsonreports a service account inprincipal, with"kind": "service_account", instead ofserviceAccount, and every document hasvalidandprincipal. A service account API key that GraphOps does not accept, such as a revoked one, is reported withvalidfalseand exit0instead of exit3. Use--checkto fail on it.--secret-file <file>replaces--output <file>for writing a new key's secret to a file, onapi-keys create,api-keys rotateandservice-accounts keys create.graphops service-accounts updatetakes--add-grant <permission>and--remove-grant <permission>to change one permission, or--grants <file>to replace them all.--grantis gone: it replaced every permission, so following a permission error's advice could remove an account's other permissions.graphops auth status -o jsonreportsexpiresAtas 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 currentandapi-keys forgetreplacegraphops rpc key,graphops subgraphs keyandgraphops substreams key, which are gone.api-keys create --storegrants every data service your organization can use unless you pass--productor--grants.api-keys storechecks the key with GraphOps and needs a sign-in. Keys stored by 0.1.0 are no longer used: store a key again withgraphops api-keys create --storeorgraphops api-keys store, and delete the old entries withgraphops api-keys forget --all. GRAPHOPS_API_KEYreplacesGRAPHOPS_RPC_API_KEY,GRAPHOPS_SUBGRAPHS_API_KEYandGRAPHOPS_SUBSTREAMS_API_KEY, which the CLI no longer reads.graphops execsetsGRAPHOPS_API_KEY, the variable the GraphOps code examples read, instead of one variable per data service, andSUBSTREAMS_API_KEYwhen the key covers Substreams.--productis optional: when you pass it,graphops execchecks that the stored key covers that data service and exits125(key_missing_product) without running your command if it doesn't.graphops execexits125when it fails before running your command, for example because a key is missing (missing_key), and126when your command can't run, instead of2or4. Your command's own exit codes pass through unchanged.graphops substreams run,guiandsinkexit125when 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,126when the Substreams CLI can't run and127when it isn't found, instead of1,2or4. 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 --networkwith a network GraphOps doesn't serve exits2(unsupported_network) and lists the supported names, instead of listing no packages.- The npm package exits
120instead of1when it can't startgraphops: on a system without a build, such as Alpine Linux, or when the package for your platform isn't installed. graphops exec --product substreamsno longer passes Substreams endpoint and credential variables from your shell, such asSUBSTREAMS_ENDPOINTorSINK_SQL_RUN_ENDPOINT, to your command. It points every network GraphOps serves at its GraphOps endpoint instead, and names the variables it removed.graphops usagedurations count whole periods, including the current one:usage daily --from 7dis today and the 6 days before.- A service account needs
apiKeys.readas well asapiKeys.revoketo revoke a key, and as well asapiKeys.renameto rename one. graphops api-keys updatethat removes a product or changes a limit needs--confirmwith the key's name or ID, and so doesgraphops service-accounts update --grantsthat removes a permission or changes a limit, with the account's name or ID. Without it they exit2withconfirmation_requiredand change nothing.graphops api-keys showlists each product on its own line with its limits, afterProducts:, instead of marking it(limited)and adding aManaged Subgraphs:line.- The
api-keyscommands refuse a value that starts like a secret (gqk_orgsk_) but is not a key ID withapi_key_unknown(exit2), 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
2when they are not a member of it. - Homebrew installs the CLI as
graphops/tap/graphops-cli.brew upgrademoves an existinggraphopsinstallation to the new name. graphops subgraphs deploy,createandstatusJSON reportscurrentQueryUrlandnextQueryUrl(null without a Next version) instead ofqueryUrl.createalso reportsdeploymentCid.graphops subgraphs status,wait,promote,unstage,rename,target-typeanddeleteJSON names each Deployment CIDdeploymentCid, asdeployandhistorydo, instead ofdeploymentHash.graphops subgraphs listJSON reportspromotion, with the sameeligible,stateandreasonasstatus, instead ofupgradeState. TheUPGRADEcolumn is nowPROMOTION.graphops subgraphs deploystops 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 deploywithout a name can also create a Managed Subgraph, andgraphops subgraphs explore,metadata,schema,entitiesandmanifestwithout--cidor--subgraph-idinspect the current version of a Managed Subgraph you choose.graphops api-keys createwithout--productasks for the data services. A Substreams run whose manifest's network cannot be read asks for the network. - A removal without
--confirm, and anapi-keys updateorservice-accounts update --grantsthat removes access, shows the plan and asks you to type the name.graphops aliases retargetandgraphops 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 execand the Substreams commands, replace a staged Next version on deploy, or wait for a version before retargeting an Endpoint Alias to it. - After
subgraphs createor 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; aftersubgraphs wait --for promotable, it offers the promotion, default no. - After a prompted run,
Next time: <command>on stderr shows the full command.
- A missing Managed Subgraph, Endpoint Alias, API key,
service account or organization is chosen from a list of your organization's.
-
graphops initsets up a new machine at a terminal: sign in, choose the organization, create and store an API key, install the agent skills and rungraphops doctor. Without a terminal it exits2and lists those commands. -
--no-input, before or after the command, andGRAPHOPS_NO_INPUTturn prompts off. The CLI also never prompts with-o json, under a coding agent or CI system it detects, or withTERM=dumb. -
graphops doctoradds aninteractivecheck that says whether the CLI may prompt, and why not. -
Exit code
130and error codecancelled: you cancelled at a prompt, and nothing changed. -
graphops subgraphs historylists the versions a Managed Subgraph has served, andgraphops subgraphs statusshows the previous version. -
graphops subgraphs deploy,createandstatusprint 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 thegraphops aliases createcommand.graphops aliases create,showandlistprint each Endpoint Alias's query URL. -
graphops subgraphs promotenames 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 addsservingAliases. -
graphops subgraphs deploy --createsays which command creates the Subgraphs API key that querying needs. -
graphops subgraphs statusandlistshow the promotion state asNot staged,Indexing,Ready to promoteorBlocked, and a version with no status yet asWaiting for indexing data. -
graphops aliasescommands name a Managed Subgraph target by its name. JSON addsmanagedSubgraphName. -
graphops subgraphs waitreports a timeout witherror.codewait_timeout, andgraphops subgraphs deployreports a refused Graph CLI argument withargument_refused. -
graphops auth statusshows who is signed in and the organization's name, and says when the session has expired or could not be checked. JSON addsprincipalandvalid. -
graphops auth status --checkexits0only when a session orGRAPHOPS_TOKENis present and GraphOps accepts it. Otherwise it exits3withnot_signed_in,session_expired,credential_rejectedorunverified, so CI can check its credential in one step. -
-o,--profileand--organizationwork after the command, as ingraphops subgraphs list -o json, as well as before it. Aftergraphops substreams run,guiandsink, every argument still goes to the Substreams CLI, and from the commandgraphops execruns 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 usageaccepts a UTC date,today,yesterdayand--from month, and marks periods that are still in progress. -
graphops usageandgraphops credits ledgersay what consumed credits:usage --by-attributionandusage windowsname 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-keyalso takes a key's name. -
graphops agent-skills checkalso reports newly published skills, with the command to install them. -
graphops substreams envprints the same variablesgraphops exec --product substreamssets, withunsetlines 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--confirmthat doesn't match. -
The
api-keyscommands take a key's name as well as its ID, and--confirmaccepts either. When several keys share the name, the command exits2withapi_key_ambiguousand lists their IDs. -
graphops api-keys revokeandrotatename the key, its products with their limits or its service account, and when it was last used. -
graphops api-keys updateandgraphops service-accounts update --grantsprint the products or permissions they added and removed and the limits they changed. JSON addsadded,removedandlimitsChanged. -
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 periodstarts at your current billing period, which follows your plan's renewal date;--from monthis the calendar month in UTC. -
graphops substreams run,guiandsinkprint the network and endpoint they stream from, and whether the network came from--networkor the manifest, or defaulted to mainnet. -
Every
--networkoption of the Substreams commands andgraphops exectakes any of a network's Substreams registry names, such asbaseorbase-mainnet, or its CAIP-2 ID, such aseip155:8453. -
graphops exectakes 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_FILEandSSL_CERT_DIRname certificates to trust instead of the operating system's. -
graphops api-keys create --storeandgraphops api-keys rotate --storestore 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 doctorchecks your organization's stored key with GraphOps: that it is still active and which data services it has. It names the variablesgraphops execsets.
Fixed
graphops aliases retargetandgraphops aliases updaterefuse to point an Endpoint Alias at a Managed Subgraph version that is not synced and healthy, unless you pass--force. For thenextbehavior they check the staged Next version, andretargetprints the old and new target.graphops subgraphs listshows each Managed Subgraph's status and hides those being deleted.graphops subgraphs waitstops at once when the Managed Subgraph is suspended or deleted.graphops subgraphs promotelets GraphOps decide whether a promotion may proceed.graphops subgraphs deployrefuses a Managed Subgraph that doesn't exist, and a Graph CLI--networkother 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 logoutwhen you're signed out, say that nothing changed. - A
--confirmvalue that doesn't match names the resource to repeat instead of printing it. graphops api-keys currentshows the same last four characters as the platform.graphops service-accounts update --add-grantand--remove-grantshow each permission with its limits, and say when a permission you add is already held and keeps its limits.graphops service-accounts update --grantnames--add-grantand--remove-grantinstead 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
--confirmvalue to copy. - When no organization is selected, the error also offers
--organization <slug>for one command. graphops substreams packages list --network baselists packages taggedbase-mainnettoo.graphops substreams run,guiandsinkaccept an option value that starts with-, such as--cursor -Xq9e2Ldw_kA, instead of refusing it as an endpoint option.graphops substreams sink webhookwithout 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 execruns 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_TOKENis reported as empty instead of "not signed in", and without a terminal the sign-in advice also namesGRAPHOPS_TOKEN. graphops doctoras a service account no longer checks device sign-in, and suggestsGRAPHOPS_API_KEYorgraphops api-keys storeinstead of creating a key, which service accounts cannot do.- Stored keys belong to an organization. After
graphops orgs useor with--organization, commands use that organization's key, and a missing key says which organization has none. Before,graphops execkept using, and billing, the key stored for the previous organization.
0.1.0
First release.
Last updated