For AI agents: the documentation index is at /llms.txt. Markdown versions of pages are available by appending .md to the URL.
Skip to main content

Quickstart with AI

Build an Envio HyperIndex indexer end-to-end with an AI coding assistant.

Most developers now reach for an AI coding assistant before they open a file. This guide walks through an AI-centric flow for creating, developing, and deploying a HyperIndex indexer. It is semi-generic, so any capable AI coding assistant (Cursor, Codex, Windsurf, Copilot Agent, Continue, etc.) will work. That said, we've seen the best results with Claude Code and recommend starting there.

Prefer the interactive flow?

If you'd rather drive the CLI yourself, see the Quickstart.

Prerequisites​

Step 1. Initialize The Indexer​

Open Claude Code, Codex or Cursor and prompt:

pnpx envio init

Built for AI Agents​

When envio init runs under an agent without a subcommand, it doesn't open the interactive prompts. It prints a plan for the agent to stderr and exits with code 2. Code 2 means "the agent has a follow-up step", not a failure. The plan tells the agent to ask you for an API token if ENVIO_API_TOKEN isn't set, work out the chain and contract from your goal, and then run envio init again with flags.

envio init treats the session as an agent when CLAUDECODE or CI is set, when TERM is dumb, or when stdout is not a terminal. Set ENVIO_TUI to override this: true or 1 forces the interactive prompts, false or 0 forces agent mode.

In agent mode, every answer comes from flags. Always pass the directory (-d) and --single-contract --all-events, so nothing waits for input. To import a verified contract from a block explorer:

pnpx envio init contract-import explorer \
  -n my-indexer \
  -c 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  -b ethereum-mainnet \
  --single-contract --all-events \
  -d my-indexer

Here -b takes a network name, such as ethereum-mainnet or base, not a chain ID, even though the printed plan shows -b ${chainId}. Run pnpx envio init contract-import explorer --help for the list of names. To import from an ABI file instead, -b takes a name or a chain ID:

pnpx envio init contract-import -c <ADDRESS> local \
  -a ./abis/MyContract.json --contract-name MyContract \
  -b 8453 \
  --single-contract --all-events \
  -d my-indexer

For a chain HyperSync doesn't support, add -r <RPC_URL> -s <START_BLOCK> to the local command. Other flags: -l typescript|rescript (default typescript) and --package-manager pnpm|npm|yarn|bun (default pnpm when it's installed, otherwise npm). Run pnpx envio init --help, or see the Envio CLI reference, for every option.

envio init then writes the project, runs codegen, installs dependencies and initializes a git repository. It ends by suggesting pnpm test as the first command for an agent.

To read these docs from the terminal, an agent can run envio tools search-docs "<query>" and envio tools fetch-docs <url> (Envio 3.1 and newer). They print plain text and need no setup or token.

Skills For Your Agent​

envio init adds 17 skills to the new project's .claude/skills/ folder, one SKILL.md per topic: config, schema, handlers, testing, factory contracts, wildcard indexing, event filters, block handlers, multichain, external calls, transactions, traces, performance, troubleshooting, running several indexers locally, the envio-cloud CLI and searching the docs. Claude Code loads them automatically.

envio init doesn't create an AGENTS.md, an .agents/ folder or Cursor rules. If your agent doesn't load skills from .claude/skills/, tell it to read them first, for example: "Read every SKILL.md under .claude/skills/ before you change the indexer."

After you upgrade envio, refresh the skills from the project root (Envio 3.0 and newer):

pnpm envio skills update

It rewrites every skill whose SKILL.md has metadata.managed-by: envio, deletes the skills that older versions shipped under other names, and leaves your own skills alone.

About Envio API Token​

The Envio API token is your HyperSync API token. A few things to know:

  • The token can't currently be created programmatically. You generate one by logging in to envio.dev/app/api-tokens and copying it into ENVIO_API_TOKEN in your indexer's .env. An agent can't do this step for you.
  • It's only required for local development and self-hosted deployments. Indexers running on Envio Cloud get special access and don't need a custom token.
  • It's required when using Envio as the data provider (HyperSync). If you only use an external RPC as the data source, no token is needed.
  • envio init reads the token from --api-token or the ENVIO_API_TOKEN environment variable and writes it to the new project's .env. In agent mode it stops with an error when the indexer uses HyperSync and neither is set. Pass --api-token "" to create the project without a token and add it to .env later. Until then the agent can still run codegen, type-check and run tests that use simulate, but tests that fetch real blocks fail with "An Envio API token is required".
  • To run pnpm dev locally, generate a token from the link above and set ENVIO_API_TOKEN in .env before starting the indexer.

See API Tokens and Environment Variables for full details.

Step 2. The Development Loop​

The skills cover config, schema, handlers, dynamic contracts, testing, and troubleshooting, so an agent can read them directly instead of inventing patterns. A productive loop looks like:

  1. Describe the behavior you want in plain English.
  2. Let the assistant edit config.yaml, schema.graphql, and src/handlers.
  3. Have it follow a test-driven loop: write a failing test with createTestIndexer(), implement the handler, then run pnpm test to capture and lock in snapshots. See the Testing guide for the full TDD workflow.
  4. Iterate on failures together.

The three files your agent will spend most of its time in:

Step 3. Migrating an Existing Indexer​

If you're porting from The Graph, Ponder, or another indexing framework, start with the AI migration workflow. It scales much better than hand-editing handlers.

Step 4. Deploy Programmatically with envio-cloud​

Once your indexer runs locally, the envio-cloud CLI lets an assistant (or a CI job) deploy and manage the hosted indexer without opening the dashboard. Envio Cloud builds from GitHub, so the assistant deploys by pushing a commit.

Two steps need you in a browser, once: sign in at envio.dev with GitHub, and install the Envio Deployments GitHub App on the repository. After that, an agent can run the loop:

npm install -g envio-cloud

envio-cloud login        # uses ENVIO_GITHUB_TOKEN or a signed-in gh CLI, else opens a browser
envio-cloud indexer add --name my-indexer --repo my-repo --branch main --yes
git push origin main
COMMIT=$(git rev-parse HEAD | cut -c1-7)
envio-cloud indexer commits my-indexer -o json            # did the commit deploy?
envio-cloud deployment logs my-indexer $COMMIT --build
envio-cloud deployment status my-indexer $COMMIT --watch-till-synced --timeout 30m
  • Envio Cloud identifies a deployment by the first 7 characters of its commit hash.
  • Pass --yes, or indexer add waits for a confirmation. Set --branch to the branch you push: the default is envio.
  • --watch-till-synced exits once every chain is ready. --timeout bounds the wait: when it runs out, the command exits with code 124 (not synced yet), so run it again.

Most commands support -o json, which makes it easy for assistants and scripts to parse results. See Deploy From an Agent or CI for commit statuses, JSON shapes and exit codes.