Graphman CLI Commands

Graphman is the command-line administration tool for Graph Node. It provides commands to manage deployments, inspect their status, and maintain the indexing infrastructure.

Usage

All Graphman commands follow this pattern:

graphman --config <CONFIG> <COMMAND> [OPTIONS] [ARGS]

--config

string

required

Path to the Graph Node configuration file (typically config.toml)

Commands Overview

Info

Display deployment details and status

Remove

Remove a named subgraph

Unassign

Stop indexing a deployment

Drop

Delete deployment and all data

Unused Record

Record unused deployments

Unused Remove

Remove recorded unused deployments

Check Blocks

Verify cached block integrity

Call Cache Remove

Clear chain call cache

Info

Prints detailed information about a deployment, including its status, location, and indexing progress.

Usage

graphman --config <CONFIG> info [OPTIONS] <DEPLOYMENT>

Arguments

DEPLOYMENT

string

required

The deployment identifier. Can be specified as:

Subgraph name: author/subgraph-name
IPFS hash: QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
Database namespace: sgdNNN
IPFS hash with shard: Qm...:shard (when the same hash is deployed in multiple shards)

Options

-c, --current

boolean

List only current version

-p, --pending

boolean

List only pending versions

-u, --used

boolean

List only used (current and pending) versions

-s, --status

boolean

Include detailed status information (sync status, health, block numbers)

Output Fields

By default, the command displays:

name - The subgraph name
status - Either pending or current
id - The IPFS hash (Qm… identifier)
namespace - Database schema containing deployment data tables
shard - Database shard location
active - Whether this is the active version for querying
chain - Blockchain network name
graph node id - Node ID assigned to this deployment

With --status flag, additional fields are shown:

synced - Whether the subgraph has synced to the current chain head
health - Can be healthy, unhealthy (syncing with errors), or failed
latest indexed block - Most recent block processed
current chain head block - Current blockchain head

Examples

graphman --config config.toml info author/subgraph-name

Example Output

name: author/subgraph-name
status: current
id: QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
namespace: sgd123
shard: primary
active: true
chain: mainnet
graph node id: default

With --status:
synced: true
health: healthy
latest indexed block: 18500000
current chain head block: 18500010

Remove

Removes the association between a subgraph name and its deployment. This stops query traffic to the named subgraph and releases the name for reuse.

No indexed data is lost. This command only removes the name mapping.

Usage

graphman --config <CONFIG> remove <NAME>

Arguments

NAME

string

required

The name of the subgraph to remove (e.g., author/subgraph-name)

Examples

graphman --config config.toml remove author/subgraph-name

Use Cases

Stop serving queries for a specific subgraph name
Release a subgraph name for another deployment
Temporarily disable a subgraph without losing data

Unassign

Makes Graph Node stop indexing a deployment permanently. The deployment is removed from all node assignments.

No indexed data is lost. The deployment data remains in the database but is no longer actively indexed.

Usage

graphman --config <CONFIG> unassign <DEPLOYMENT>

Arguments

DEPLOYMENT

string

required

The deployment identifier (see info command for supported formats)

Examples

graphman --config config.toml unassign author/subgraph-name

Refer to the Maintenance Documentation for more details about deployment assignment management.

Unused Record

Inspects all shards for unused deployments and registers them in the unused_deployments table. This is the first step before removing unused deployment data.

No indexed data is lost. This command only records which deployments are unused.

Usage

graphman --config <CONFIG> unused record

Unused Deployment Criteria

A deployment is considered unused if it meets ALL of these criteria:

Not assigned to any node
Either not marked as active OR is neither the current nor pending version of a subgraph
Not the source of a currently running copy operation

Examples

graphman --config config.toml unused record

Workflow

This command is typically followed by unused remove to actually delete the recorded unused deployments:

# Step 1: Record unused deployments
graphman --config config.toml unused record

# Step 2: Remove them (after verification)
graphman --config config.toml unused remove

Unused Remove

Removes all indexed data from deployments previously marked as unused by the unused record command.

This operation is irreversible. All data from the selected deployments will be permanently deleted.

Usage

graphman --config <CONFIG> unused remove [OPTIONS]

Options

-c, --count

number

Maximum number of unused deployments to remove (default: all)

-d, --deployment

string

Remove a specific deployment by its identifier

-o, --older

number

Remove only deployments recorded at least this many minutes ago

Removal Order

Deployments are removed in descending order by number of entities (smaller deployments first, larger ones last).

Examples

graphman --config config.toml unused remove

Drop

Stops, unassigns, and deletes all indexed data from a deployment in a single operation.

This operation is irreversible. The deployment will be completely removed with all its data.

Usage

graphman --config <CONFIG> drop [OPTIONS] <DEPLOYMENT>

Arguments

DEPLOYMENT

string

required

The deployment identifier (name, IPFS hash, or namespace)

Options

-c, --current

boolean

Search only for current versions

-p, --pending

boolean

Search only for pending versions

-u, --used

boolean

Search only for used (current and pending) versions

-f, --force

boolean

Skip confirmation prompt

What It Does

The drop command is equivalent to running these commands in sequence:

graphman info <search term>
graphman unassign <deployment id>
graphman remove <deployment name>
graphman unused record
graphman unused remove <deployment id>

Examples

graphman --config config.toml drop QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

Check Blocks

Compares cached blocks with fresh data from the JSON RPC provider and clears any blocks that differ. This helps diagnose and fix issues with invalid block data from RPC providers.

Usage

graphman --config <CONFIG> chain check-blocks <CHAIN_NAME> <SUBCOMMAND>

Arguments

CHAIN_NAME

string

required

Chain name (must be an existing chain, see chain list)

Subcommands

by-hash
by-number
by-range

Check a specific block by its hash.

graphman --config <CONFIG> chain check-blocks <CHAIN_NAME> by-hash <HASH>

HASH

string

required

The block hash (e.g., 0xd56a9f64c7e696cfeb337791a7f4a9e81841aaf4fcad69f9bf2b2e50ad72b972)

Check a specific block by its number.

graphman --config <CONFIG> chain check-blocks <CHAIN_NAME> by-number <NUMBER> [--delete-duplicates]

NUMBER

number

required

The block number

--delete-duplicates

boolean

Delete all duplicated blocks for the given number and continue

Check a range of blocks.

graphman --config <CONFIG> chain check-blocks <CHAIN_NAME> by-range [OPTIONS]

-f, --from

number

Starting block number (omit for open lower bound)

-t, --to

number

Ending block number (omit for open upper bound)

--delete-duplicates

boolean

Delete all duplicated blocks and continue

Handling Duplicates

JSON RPC providers may sometimes return different blocks for the same block number. When this happens, Graphman cannot automatically determine which is correct and will abort unless you specify --delete-duplicates, which removes all duplicated blocks before proceeding.

Examples

graphman --config config.toml chain check-blocks mainnet by-hash 0xd56a9f64c7e696cfeb337791a7f4a9e81841aaf4fcad69f9bf2b2e50ad72b972

Call Cache Remove

Removes entries from the chain call cache. The call cache stores results of contract calls to improve indexing performance.

Removing the entire cache can significantly reduce indexing performance and should generally be avoided.

Usage

graphman --config <CONFIG> chain call-cache <CHAIN_NAME> remove [OPTIONS]

Arguments

CHAIN_NAME

string

required

The name of the chain

Options

--remove-entire-cache

boolean

Remove the entire call cache for the chain

--ttl-days

number

Remove stale contracts not accessed in this many days (based on call_meta.accessed_at)

--ttl-max-contracts

number

Limit the number of contracts to consider for stale removal

-f, --from

number

Starting block number for range-based removal

-t, --to

number

Ending block number for range-based removal

Removal Strategies

Range-Based Removal

Remove cache entries for a specific block range:

graphman --config config.toml chain call-cache ethereum remove --from 10 --to 20

If --from is omitted, starts from the first block. If --to is omitted, continues to the last block.

TTL-Based Removal

Remove cache entries for contracts that haven’t been accessed recently:

# Remove contracts not accessed in 7 days
graphman --config config.toml chain call-cache ethereum remove --ttl-days 7

# Limit to 100 contracts
graphman --config config.toml chain call-cache ethereum remove --ttl-days 7 --ttl-max-contracts 100

Complete Removal

Remove the entire call cache:

graphman --config config.toml chain call-cache ethereum remove --remove-entire-cache

Use with caution: This will significantly impact indexing performance.

Examples

graphman --config config.toml chain call-cache ethereum remove --from 10 --to 20

Best Practices

Always Use --config

Always specify the configuration file path with --config to ensure commands operate on the correct Graph Node instance.

Verify Before Dropping

Use info command to verify deployment details before running destructive operations like drop.

Two-Step Cleanup

Use unused record followed by unused remove instead of immediately dropping deployments. This gives you time to verify.

Monitor Block Cache

Regularly use check-blocks to ensure RPC provider data integrity, especially after RPC provider changes.

GraphQL API

Graphman CLI

Subgraph Manifest

​Usage

​Commands Overview

Info

Remove

Unassign

Drop

Unused Record

Unused Remove

Check Blocks

Call Cache Remove

​Info

​Usage

​Arguments

​Options

​Output Fields

​Examples

​Remove

​Usage

​Arguments

​Examples

​Use Cases

​Unassign

​Usage

​Arguments

​Examples

​Related Documentation

​Unused Record

​Usage

​Unused Deployment Criteria

​Examples

​Workflow

​Unused Remove

​Usage

​Options

​Removal Order

​Examples

​Drop

​Usage

​Arguments

​Options

​What It Does

​Examples

​Check Blocks

​Usage

​Arguments

​Subcommands

​Handling Duplicates

​Examples

​Call Cache Remove

​Usage

​Arguments

​Options

​Removal Strategies

​Examples

​Best Practices

Always Use --config

Verify Before Dropping

Two-Step Cleanup

Monitor Block Cache

​See Also

Build docs developers (and LLMs) love

Usage

Commands Overview

Info

Usage

Arguments

Options

Output Fields

Examples

Remove

Usage

Arguments

Examples

Use Cases

Unassign

Usage

Arguments

Examples

Related Documentation

Unused Record

Usage

Unused Deployment Criteria

Examples

Workflow

Unused Remove

Usage

Options

Removal Order

Examples

Drop

Usage

Arguments

Options

What It Does

Examples

Check Blocks

Usage

Arguments

Subcommands

Handling Duplicates

Examples

Call Cache Remove

Usage

Arguments

Options

Removal Strategies

Examples

Best Practices

See Also