subgraph-deploy

name	subgraph-deploy
description	Deploy built subgraphs to ORMI infrastructure and verify deployment health. Use when user says "deploy my subgraph", "publish to ORMI", or "push to production".

Subgraph Deploy Skill

Deploy a built subgraph to ORMI infrastructure and confirm it is indexing correctly.

When to Use

User has a built subgraph (ormi-cli build succeeds) and wants to deploy to ORMI.

CLI-First Rule

Use ormi-cli for build and deploy commands; use MCP tools for authentication, key retrieval, discovery, and post-deploy inspection.

• Use ormi-cli create, ormi-cli codegen, ormi-cli build, and ormi-cli deploy for the release flow
• Use MCP tools (whoami, list-projects, list-project-tokens, etc.) for authentication and API key retrieval — there are no CLI equivalents for these operations
• Do not bypass the CLI by describing manual upload steps unless the CLI path has already failed

Step 1: Authenticate and Get Deploy Key

1a: Check MCP Authentication

Call the MCP whoami tool (do NOT run ormi-cli whoami — this CLI command does not exist):

{
  "tool": "whoami"
}

Branch on result:

• whoami succeeds (returns email, name, etc.) → continue to Step 1b
• whoami fails (auth error) → tell the user:

  MCP is not authenticated. Run /mcp to authenticate with ormi, then try again. STOP here. Do not continue. Do not offer alternatives.

• MCP server unavailable (tool not found, connection error) → ask the user:

  MCP is not available. Please provide your deploy key directly (find it at ORMI App → Settings → API Keys), or run /mcp to configure MCP first. If the user provides a key, use it directly in Steps 3 and 5. If not, STOP.

1b: Resolve Project and Fetch Deploy Key

1. Resolve project — call MCP list-projects, then select-project if needed, or auto-select if only one
2. Fetch tokens — call MCP list-project-tokens with the project ID
3. Select token — use the first token's Key field

If no tokens exist:

No API tokens found for this project. Create one at ORMI App → Settings → API Keys. Then run this deploy again.

Step 2: Gather Deploy Inputs

Before deploying, collect and confirm:

Input	Required	How to Determine
Project	Yes	Ask user; use MCP list-projects / select-project
Subgraph name	Yes	Confirm with user; check via MCP search-project-subgraphs
Version label	Yes	Ask user (e.g., "v0.0.1")

Ask the user:

1. "Which project do you want to deploy to?" (if multiple; auto-select if only one)
2. "What is the subgraph name?"
3. "What version label? (e.g., v0.0.1)"

Step 3: Register the Subgraph Name

Before deploying, the subgraph name must be registered on ORMI. Skip this step if the name is already registered.

ormi-cli create <subgraph-name> --deploy-key <key>

If the name is already registered, the command will report an error — this is safe to ignore only if the error indicates the name already exists. Do not ignore authentication or network errors. If registration succeeds, proceed to the build step.

Step 4: Ensure the Build is Current

ormi-cli codegen
ormi-cli build

If the build fails, fix the build errors — check the error table in the subgraph-create skill for common solutions. Do not deploy broken code.

Step 5: Confirm and Deploy

Summarize before executing:

Setting	Value
Project	<project-name>
Subgraph	<subgraph-name>
Version	<version-label>
Deploy key	✓ (from MCP)

Then execute:

ormi-cli deploy <subgraph-name> --deploy-key <key-from-mcp> --version-label <version>

The deploy command will:

1. Compile the subgraph (if not already built)
2. Upload build artifacts to ORMI IPFS
3. Deploy to the ORMI subgraph node
4. Print the playground and query endpoint URLs

Step 6: Verify Deployment

Immediately after deploy, check that indexing has started:

If MCP is available:

1. Find the deployment: use search-project-subgraphs MCP tool
2. Check sync status: use get-subgraph-status MCP tool
   • Look for synced: false with a non-zero latestBlock — indexing is in progress
   • synced: true — fully caught up
3. Check for errors: use get-subgraph-logs MCP tool
   • Any ERROR entries indicate mapping handler failures — fix and redeploy
4. Track indexing speed: use get-block-stats MCP tool

If MCP is unavailable:

• Query the GraphQL endpoint printed by the deploy command:

  curl -X POST <ENDPOINT_URL> \
    -H "Content-Type: application/json" \
    -d '{"query": "{ _meta { block { number } hasIndexingErrors } }"}'
  

• Check the ORMI web UI for deployment status

Step 7: Subsequent Deployments

For code updates, bump the version label:

ormi-cli deploy <subgraph-name> --deploy-key <key-from-mcp> --version-label v0.0.2

ORMI keeps deployment history. The latest version receives queries by default.

Step 8: Verify Data (Once Synced)

Once synced, verify the indexed data:

If MCP is available: Use the execute-query MCP tool with a simple query:

{
  transfers(first: 5, orderBy: timestamp, orderDirection: desc) {
    id
    from {
      id
    }
    to {
      id
    }
    amount
  }
}

If MCP is unavailable: Query the GraphQL endpoint directly:

curl -X POST <ENDPOINT_URL> \
  -H "Content-Type: application/json" \
  -d '{"query": "{ transfers(first: 5) { id } }"}'

Compare results against on-chain data to confirm correctness.

Examples

Example 1: First deployment with MCP

• User says: "Deploy my subgraph"
• Actions:
  1. Run whoami via MCP to verify authentication
  2. Call list-projects to resolve the project
  3. Call list-project-tokens to get the deploy key
  4. Confirm project, subgraph name, and version label with user
  5. Run ormi-cli create my-subgraph --deploy-key <key> to register
  6. Run ormi-cli deploy my-subgraph --deploy-key <key> --version-label v0.0.1
  7. Verify with get-subgraph-status MCP tool
• Result: Subgraph deployed and indexing confirmed

Example 2: Deploy without MCP (direct key)

• User says: "Deploy using this key: abc123"
• Actions:
  1. Skip MCP auth, use provided deploy key
  2. Run ormi-cli codegen && ormi-cli build to ensure build is current
  3. Run ormi-cli deploy my-subgraph --deploy-key abc123 --version-label v0.0.2
  4. Verify via curl to the printed endpoint
• Result: Subgraph redeployed with new version

Common Issues

Problem	Fix
Auth failure during deploy	Run /mcp to authenticate with ormi, then retry. If MCP is unavailable, provide --deploy-key directly
IPFS upload timeout	Check network; retry with --ipfs pointing to an alternative node
Indexing errors in logs	Fix handler code, redeploy with incremented version label
Slow indexing	Normal for historical data — monitor with get-block-stats
No API tokens found	Create one at ORMI App → Settings → API Keys

For ongoing monitoring after deployment, use the subgraph-monitor skill.

Direct CLI Usage (Without Skill)

If the user prefers to deploy directly without the skill:

# Register the subgraph name (first time only)
ormi-cli create <subgraph-name> --deploy-key <key>

# Provide deploy key via flag
ormi-cli deploy <subgraph-name> --deploy-key <key> --version-label v0.0.1

# Or via environment variable
ORMI_DEPLOY_KEY=<key> ormi-cli deploy <subgraph-name> --version-label v0.0.1

MCP Tools Used

• whoami — verify MCP authentication (MCP tool only — NOT a CLI command)
• list-projects / select-project — resolve project
• list-project-tokens — fetch deploy key
• search-project-subgraphs — find the deployment
• get-subgraph-status — check sync progress
• get-subgraph-logs — watch for indexing errors
• get-block-stats — track indexing speed
• execute-query — verify indexed data