Graphman CLI Commands

Complete reference for all Graphman command-line tools to manage Graph Node deployments

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

By Name

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

graphman --config config.toml info QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

graphman --config config.toml info QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66 --status

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

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

By Name

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

graphman --config config.toml unassign QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

Related Documentation

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:

1. Not assigned to any node
2. Either not marked as active OR is neither the current nor pending version of a subgraph
3. 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

Remove All

graphman --config config.toml unused remove

# Remove deployments unused for 12+ hours
graphman --config config.toml unused remove --older 720

graphman --config config.toml unused remove --deployment QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

# Remove up to 5 unused deployments
graphman --config config.toml unused remove --count 5

---

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:

1. graphman info <search term>
2. graphman unassign <deployment id>
3. graphman remove <deployment name>
4. graphman unused record
5. graphman unused remove <deployment id>

Examples

By Hash

graphman --config config.toml drop QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66

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

graphman --config config.toml drop author/subgraph-name --force

---

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

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)

by-number

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

by-range

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

By Hash

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

graphman --config config.toml chain check-blocks mainnet by-number 15626962

graphman --config config.toml chain check-blocks mainnet by-range --from 15626900 --to 15626962 --delete-duplicates

# Check all blocks from 13000000 onwards
graphman --config config.toml chain check-blocks mainnet by-range --from 13000000

---

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

Block Range

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

graphman --config config.toml chain call-cache ethereum remove --ttl-days 7

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

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

---

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.

See Also

• Graphman GraphQL API - Manage deployments via GraphQL
• Graph Node Maintenance - Detailed maintenance procedures