# CLI release notes

Source: https://docs.graphops.xyz/platform/cli/release-notes

Check these notes before you update the GraphOps CLI. `graphops --version` shows the version you
have, and [Update or remove the CLI](/platform/cli#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](/platform/cli#error-codes). 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](/platform/cli#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](/platform/cli#error-codes) 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.