Skip to content

Scripts, CI and coding agents

Read the GraphOps CLI's JSON output in scripts, sign in a CI job as a service account, pin the CLI version, and let a coding agent use the CLI as you.

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 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, 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:

CLI · GraphOps CLI

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.

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 covers the skills and the docs MCP server.

Next steps

Last updated