# Developer workflow

Source: https://docs.graphops.xyz/platform/cli/developer-workflow

Build against GraphOps without pasting an API key into `.env` files, shell profiles or command
history. Store the key once in your operating system's credential store, then let `graphops` hand
it to each command or application you run, and to nothing else.

This page follows a typical local loop: store a key, check what is configured, then call each data
service with it.

## Prerequisites

* The [GraphOps CLI](/platform/cli), signed in to your organization with `graphops auth login`.
* The owner or developer role, to create a key. Creating a key also needs a sign-in from the last
12 hours.

## Store an API key in your credential store

```sh
# Create an API key for every data service your organization can use, and store it in your
# operating system's credential store. The secret is never printed.
graphops api-keys create --store --name laptop

# Or store a key you already have: paste it at the prompt, which does not echo it.
graphops api-keys store

```

`graphops api-keys create --store` creates a query key with every data service your organization
can use and stores it without printing it. Pass `--product rpc` (repeat for several) to grant only
some. `graphops api-keys store` reads a key you already created in
**API keys** from a prompt that does not echo it, or from standard input as
in `pbpaste | graphops api-keys store`. The CLI checks that the key is an active key of your
organization before storing it.

### Where the key is kept

The CLI keeps your sign-in session and each organization's stored key in your operating system's
credential store:

| System        | Credential store                                                      |
| ------------- | --------------------------------------------------------------------- |
| macOS         | The login Keychain. macOS can ask you to allow `graphops` to read it. |
| Linux desktop | The Secret Service, such as GNOME Keyring or KWallet.                 |
| Windows       | Windows Credential Manager.                                           |

Entries are filed under the service `graphops-cli`. The CLI's configuration directory keeps only
metadata about the key, such as its ID, name, data services and last four characters, never the
secret.

Where no credential store is available, such as a Linux server without a desktop session or an SSH
session on Windows, the CLI keeps secrets in `secrets.toml` in its configuration directory and
prints a warning whenever it uses that file. On macOS and Linux the file is readable only by you,
and the CLI refuses to read it once other users can. On Windows it is protected only by its
folder's permissions. Anyone with your user account or a copy of the file can use the secrets. On a
server or in CI, set `GRAPHOPS_API_KEY` instead, which is never stored; see
[Scripts, CI and coding agents](/platform/cli/automation).

## Check what is configured

```sh
# Who is signed in, the organization, and where secrets live: "secret store: keychain".
graphops auth status

# The key graphops exec uses: its ID, name, data services and last four characters.
graphops api-keys current

# Check the whole setup, including that the stored key is still active.
graphops doctor

```

* `graphops auth status` shows who is signed in, the organization commands act in, and which store
holds your secrets: `secret store: keychain` for the operating system's credential store, or
`secret store: file <path>` for `secrets.toml`.
* `graphops api-keys current` shows the key your commands use: its ID, name, data services and
last four characters. When `GRAPHOPS_API_KEY` is set in your shell, it reports that variable's key
instead, because the variable takes precedence over the stored key. `--reveal` also prints the
secret.
* `graphops doctor` checks your sign-in, organization, credential store, that the stored key is
still active, and the variables `graphops exec` sets. It prints a fix for each check that fails.

### Switch organization, replace or forget a key

```sh
# Each organization has its own stored key: switching organization switches the key.
graphops orgs use other-organization
graphops api-keys current

# Replace the stored key. The previous key keeps working until you revoke it.
graphops api-keys create --store --replace --name laptop

# Forget the stored key. Forgetting does not revoke it.
graphops api-keys forget

```

Each organization has its own stored key. After `graphops orgs use <organization>`, or with
`--organization`, commands use that organization's key, never the previous one. Each configuration
profile (`--profile`) and configuration directory (`GRAPHOPS_CONFIG_DIR`) keeps its own keys too.

`graphops api-keys create --store --replace` stores a new key in place of the old one and names the
old key, which keeps working until you revoke it. `graphops api-keys forget` removes the stored key
from your machine without revoking it. To stop a key working, revoke it with
`graphops api-keys revoke`; see [Manage keys and service accounts](/platform/cli/api-keys).

## Run your code with the key

```sh
# Run your application with the key in GRAPHOPS_API_KEY, set for this process only.
graphops exec node index.js

# Options for graphops exec go first; everything after the command is passed to it unchanged.
graphops exec --product rpc -- npm run dev

```

`graphops exec` runs your command with the key in `GRAPHOPS_API_KEY`, the variable every GraphOps
code example reads, and in no other process. When the key covers Substreams, it is also set as
`SUBSTREAMS_API_KEY`. The key stays out of your shell history and your shell's environment, but
anything your code prints, including its environment, can show it.

* Put the `exec` options first. Everything from your command onward is passed to it unchanged,
even arguments such as `--help`. A `--` before your command is optional.
* `--product <service>` checks that the stored key covers a data service before your command runs,
and exits `125` without running it if not. The CLI cannot check a key you set in
`GRAPHOPS_API_KEY`, so it runs your command with that key as given.
* Your command's output and exit code are its own. When `graphops exec` fails before your command
starts, for example because no key is stored, it exits `125`, so a script or process supervisor
can tell its failures from your program's.

When the key covers Substreams, or with `--product substreams`, your command does not receive the
Substreams endpoint or credential variables your shell already has, such as
`SUBSTREAMS_ENDPOINT` or `SUBSTREAMS_API_TOKEN`, so an endpoint set for another provider cannot
receive your GraphOps key. Instead, every network GraphOps serves points at its GraphOps endpoint.
Add `--network <network>` to also set `SUBSTREAMS_ENDPOINT` to the GraphOps endpoint for that
network. `--network` takes any of a network's Substreams registry names, such as `base` or
`base-mainnet`, or its CAIP-2 ID, such as `eip155:8453`.

## Call RPC with curl

Your shell expands `$GRAPHOPS_API_KEY` before `graphops` starts, when the variable is not set yet.
Wrap the request in `sh -c '…'` so the variable expands inside the command `graphops exec` runs:

```sh
# sh -c expands $GRAPHOPS_API_KEY inside the command graphops runs, not in your shell.
graphops exec --product rpc -- sh -c '
  curl --fail-with-body --silent --show-error "https://rpc.graphops.xyz/v1/evm/1" \
    -H "Authorization: Bearer $GRAPHOPS_API_KEY" \
    -H "Content-Type: application/json" \
    --data "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"eth_blockNumber\", \"params\": []}"'

```

The response is the latest Ethereum block number as a hexadecimal quantity, such as
`{"jsonrpc":"2.0","id":1,"result":"0x193a60d"}`. Replace `1` in the URL with another chain ID from
[Supported networks](/rpc/networks), and see [RPC methods](/rpc/methods) for what you can
call.

## Explore and query Subgraphs

Look at a published Subgraph's schema before you write a query against it. These commands use your
sign-in, not your API key:

```sh
# Find a published Subgraph, then read its schema and entities before you write a query.
graphops subgraphs browse --search uniswap --network mainnet
graphops subgraphs entities --subgraph-id <SUBGRAPH_ID>
graphops subgraphs schema --subgraph-id <SUBGRAPH_ID>

```

`browse` prints each Subgraph's Graph Network Subgraph ID and current Deployment CID. Pass either
to `entities`, `schema`, `manifest` or `metadata` with `--subgraph-id` or `--cid`.
[Manage Subgraphs and Endpoint Aliases](/platform/cli/subgraphs#explore-published-subgraphs) lists
them all.

Then query it with your stored key:

```sh
# GraphQL errors can arrive with HTTP 200: check the response for an "errors" array.
graphops exec --product subgraphs -- sh -c '
  curl --fail-with-body --silent --show-error "https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>" \
    -H "Authorization: Bearer $GRAPHOPS_API_KEY" \
    -H "Content-Type: application/json" \
    --data "{\"query\": \"{ _meta { deployment block { number } hasIndexingErrors } }\"}"'

```

`_meta.block.number` shows how far the deployment has indexed, and `_meta.deployment` which
version answered. A Graph Network Subgraph ID follows each version its owner publishes; give a
production application an Endpoint Alias instead.
[Identifier types](/subgraphs/concepts/identifier-types) explains the choice, and
[Query a Subgraph](/subgraphs/guides/query-a-subgraph) covers variables, errors and clients.

### Iterate on your own Subgraph

From your Subgraph project, deploy each change to a Managed Subgraph and test it
before it serves anything else:

```sh
# From your Subgraph project: build with your Graph CLI and create the Managed Subgraph.
graphops subgraphs deploy my-subgraph --create
graphops subgraphs endpoint-aliases create my-subgraph-dev --managed-subgraph my-subgraph

# After each change: stage the new build as Next, wait until it can be promoted, then promote it.
graphops subgraphs deploy my-subgraph
graphops subgraphs wait my-subgraph --for promotable
graphops subgraphs promote my-subgraph

```

The first deploy creates the Managed Subgraph, and indexing and its charges start then. Each later
deploy stages the build as the Next version while the Current version keeps serving, and the
Endpoint Alias moves only when you promote. A Managed Subgraph needs a monthly plan.
[Deploy your own Subgraph](/subgraphs/guides/deploy-your-subgraph) walks through the first deploy,
and [Develop and release a Subgraph](/subgraphs/guides/develop-and-release) covers testing,
rollback and releasing from CI.

## Stream and sink Substreams

`graphops substreams run` reads the package's network, adds the GraphOps endpoint for it and gives
your stored key to the Substreams CLI. `graphops substreams sink protojson` writes the same output
to JSONL files:

```sh
# The package's network selects the GraphOps endpoint; graphops adds the endpoint and your key.
graphops substreams run \
  "https://spkg.io/v1/packages/ethereum-common/v0.4.0" \
  "filtered_events" \
  --params "filtered_events=evt_addr:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 && evt_sig:0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" \
  --start-block 18000000 \
  --stop-block 18000010 \
  -o jsonl

# Write the same range to a JSONL file in ./output, one file per 10 blocks.
graphops substreams sink protojson \
  "https://spkg.io/v1/packages/ethereum-common/v0.4.0" \
  "filtered_events" \
  --params "filtered_events=evt_addr:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 && evt_sig:0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" \
  --start-block 18000000 \
  --stop-block 18000010 \
  --blocks-per-file 10

```

This streams the USDC Transfer events in ten Ethereum blocks with the pinned
`ethereum-common@v0.4.0` package, then writes them to
`./output/0018000000-0018000010.jsonl`. The sink saves its cursor in `./state.yaml`, so running it
again continues after the last block it wrote. Delete `state.yaml` to start over.

`graphops substreams sink` also runs the `noop` and `webhook` sinks. Run any other sink, such as
the Postgres sink, through `graphops exec`, and use `graphops substreams env` to export the
endpoint and key for a tool that reads them from your shell.
[Run Substreams with the GraphOps CLI](/substreams/guides/run-with-graphops-cli) shows both.

## Next steps

* [Deploy your own Subgraph](/subgraphs/guides/deploy-your-subgraph): Create a Managed Subgraph from your project.
* [Run Substreams with the GraphOps CLI](/substreams/guides/run-with-graphops-cli): Run sinks and export the endpoint for other tools.
* [Scripts, CI and coding agents](/platform/cli/automation): Use the CLI where no one signs in, with keys that are never stored.