# Scripts, CI and coding agents

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

Use the same commands you run at your terminal where no one can answer a prompt: in scripts, in CI
jobs and from coding agents. Ask for JSON, sign in with a service account key, and pin the CLI's
version so a release can't change what your automation reads.

## Read JSON output in scripts

Add `-o json` (`--output json`), as in `graphops subgraphs list -o json`, to get one JSON document
on standard output. Messages go to standard error. `-o`, `--profile`, `--organization` and
`--no-input` work before or after the command.

`graphops exec` and `graphops substreams run`, `gui` and `sink` print the output of the command
they run, so they refuse `-o json`, and so does `graphops self-update` without `--check`, which
prints the output of npm or Homebrew. Every argument after `graphops substreams run`, `gui` or
`sink <sink>` goes to the Substreams CLI, and every argument from the command `graphops exec` runs
onward goes to that command, so put these options before `substreams`, or before the command
`exec` runs.

A failed command prints an error document with a stable `code`, and exits with a code that tells
failure classes apart. [Reference](/platform/cli/reference#error-codes) lists both, and when a
retry can succeed.

Without a terminal, the CLI never prompts: a missing argument is a usage error, and a removal needs
`--confirm`. Pass `--no-input`, or set `GRAPHOPS_NO_INPUT`, to turn prompts off at a terminal too.

## 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.
Start the job with `graphops auth status --check`. It exits `3` with `not_signed_in` when the
variable is missing or empty, and with `credential_rejected` when GraphOps does not accept the key,
for example because it was revoked.

Install an exact version in CI, so a new release can't change the commands and JSON output your
job relies on. Move to a new version after reading its [release notes](/platform/cli/release-notes):

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

```

For code that queries a data service, set `GRAPHOPS_API_KEY` to a query key instead of storing one:
`graphops exec` and the Substreams commands use it, and it is never stored.

Commands that act as a person do not run as a service account: `auth login`, `auth logout`,
`auth token`, `orgs list`, `orgs use`, `api-keys create --store`, and the `api-keys` and
`service-accounts` commands that create or change credentials. The Subgraphs release guide lists
the [permissions a release needs](/subgraphs/guides/develop-and-release#release-from-ci).

## 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, and `graphops doctor` warns about either. `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. The CLI never prompts while it is set, and the GraphOps skills also
tell agents to pass `--no-input`.

A coding agent must have your agreement before it runs a command that removes or replaces
something. `--confirm` guards against typos; it is not your approval.
[Use GraphOps with AI agents](/ai-agents) covers the skills and the docs MCP server.

## Next steps

* [Develop and release a Subgraph](/subgraphs/guides/develop-and-release#release-from-ci): Stage and promote each build from a CI job.
* [Reference](/platform/cli/reference): Look up environment variables, exit codes and error codes.
* [Manage keys and service accounts](/platform/cli/api-keys): Create the service account and key your pipeline uses.