> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/graphprotocol/graph-node/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
graphman --config <CONFIG> <COMMAND> [OPTIONS] [ARGS]
```

<ParamField path="--config" type="string" required>
  Path to the Graph Node configuration file (typically `config.toml`)
</ParamField>

## Commands Overview

<CardGroup cols={2}>
  <Card title="Info" icon="circle-info" href="#info">
    Display deployment details and status
  </Card>

  <Card title="Remove" icon="trash" href="#remove">
    Remove a named subgraph
  </Card>

  <Card title="Unassign" icon="link-slash" href="#unassign">
    Stop indexing a deployment
  </Card>

  <Card title="Drop" icon="circle-xmark" href="#drop">
    Delete deployment and all data
  </Card>

  <Card title="Unused Record" icon="database" href="#unused-record">
    Record unused deployments
  </Card>

  <Card title="Unused Remove" icon="broom" href="#unused-remove">
    Remove recorded unused deployments
  </Card>

  <Card title="Check Blocks" icon="cube" href="#check-blocks">
    Verify cached block integrity
  </Card>

  <Card title="Call Cache Remove" icon="memory" href="#call-cache-remove">
    Clear chain call cache
  </Card>
</CardGroup>

***

## Info

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

### Usage

```bash theme={null}
graphman --config <CONFIG> info [OPTIONS] <DEPLOYMENT>
```

### Arguments

<ParamField path="DEPLOYMENT" type="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)
</ParamField>

### Options

<ParamField path="-c, --current" type="boolean">
  List only current version
</ParamField>

<ParamField path="-p, --pending" type="boolean">
  List only pending versions
</ParamField>

<ParamField path="-u, --used" type="boolean">
  List only used (current and pending) versions
</ParamField>

<ParamField path="-s, --status" type="boolean">
  Include detailed status information (sync status, health, block numbers)
</ParamField>

### 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

<CodeGroup>
  ```bash By Name theme={null}
  graphman --config config.toml info author/subgraph-name
  ```

  ```bash By Hash theme={null}
  graphman --config config.toml info QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
  ```

  ```bash With Status theme={null}
  graphman --config config.toml info QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66 --status
  ```

  ```bash Current Version Only theme={null}
  graphman --config config.toml info author/subgraph-name --current
  ```
</CodeGroup>

<Accordion title="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
  ```
</Accordion>

***

## 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.

<Warning>
  No indexed data is lost. This command only removes the name mapping.
</Warning>

### Usage

```bash theme={null}
graphman --config <CONFIG> remove <NAME>
```

### Arguments

<ParamField path="NAME" type="string" required>
  The name of the subgraph to remove (e.g., `author/subgraph-name`)
</ParamField>

### Examples

```bash theme={null}
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.

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

### Usage

```bash theme={null}
graphman --config <CONFIG> unassign <DEPLOYMENT>
```

### Arguments

<ParamField path="DEPLOYMENT" type="string" required>
  The deployment identifier (see `info` command for supported formats)
</ParamField>

### Examples

<CodeGroup>
  ```bash By Name theme={null}
  graphman --config config.toml unassign author/subgraph-name
  ```

  ```bash By Hash theme={null}
  graphman --config config.toml unassign QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
  ```
</CodeGroup>

### Related Documentation

Refer to the [Maintenance Documentation](https://github.com/graphprotocol/graph-node/blob/master/docs/maintenance.md#modifying-assignments) 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.

<Info>
  No indexed data is lost. This command only records which deployments are unused.
</Info>

### Usage

```bash theme={null}
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

```bash theme={null}
graphman --config config.toml unused record
```

### Workflow

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

```bash theme={null}
# 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.

<Warning>
  This operation is **irreversible**. All data from the selected deployments will be permanently deleted.
</Warning>

### Usage

```bash theme={null}
graphman --config <CONFIG> unused remove [OPTIONS]
```

### Options

<ParamField path="-c, --count" type="number">
  Maximum number of unused deployments to remove (default: all)
</ParamField>

<ParamField path="-d, --deployment" type="string">
  Remove a specific deployment by its identifier
</ParamField>

<ParamField path="-o, --older" type="number">
  Remove only deployments recorded at least this many minutes ago
</ParamField>

### Removal Order

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

### Examples

<CodeGroup>
  ```bash Remove All theme={null}
  graphman --config config.toml unused remove
  ```

  ```bash Time-Based Removal theme={null}
  # Remove deployments unused for 12+ hours
  graphman --config config.toml unused remove --older 720
  ```

  ```bash Specific Deployment theme={null}
  graphman --config config.toml unused remove --deployment QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
  ```

  ```bash Limited Count theme={null}
  # Remove up to 5 unused deployments
  graphman --config config.toml unused remove --count 5
  ```
</CodeGroup>

***

## Drop

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

<Warning>
  This operation is **irreversible**. The deployment will be completely removed with all its data.
</Warning>

### Usage

```bash theme={null}
graphman --config <CONFIG> drop [OPTIONS] <DEPLOYMENT>
```

### Arguments

<ParamField path="DEPLOYMENT" type="string" required>
  The deployment identifier (name, IPFS hash, or namespace)
</ParamField>

### Options

<ParamField path="-c, --current" type="boolean">
  Search only for current versions
</ParamField>

<ParamField path="-p, --pending" type="boolean">
  Search only for pending versions
</ParamField>

<ParamField path="-u, --used" type="boolean">
  Search only for used (current and pending) versions
</ParamField>

<ParamField path="-f, --force" type="boolean">
  Skip confirmation prompt
</ParamField>

### 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

<CodeGroup>
  ```bash By Hash theme={null}
  graphman --config config.toml drop QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
  ```

  ```bash By Name theme={null}
  graphman --config config.toml drop author/subgraph-name
  ```

  ```bash With Force theme={null}
  graphman --config config.toml drop author/subgraph-name --force
  ```
</CodeGroup>

***

## 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

```bash theme={null}
graphman --config <CONFIG> chain check-blocks <CHAIN_NAME> <SUBCOMMAND>
```

### Arguments

<ParamField path="CHAIN_NAME" type="string" required>
  Chain name (must be an existing chain, see `chain list`)
</ParamField>

### Subcommands

<Tabs>
  <Tab title="by-hash">
    Check a specific block by its hash.

    ```bash theme={null}
    graphman --config <CONFIG> chain check-blocks <CHAIN_NAME> by-hash <HASH>
    ```

    <ParamField path="HASH" type="string" required>
      The block hash (e.g., `0xd56a9f64c7e696cfeb337791a7f4a9e81841aaf4fcad69f9bf2b2e50ad72b972`)
    </ParamField>
  </Tab>

  <Tab title="by-number">
    Check a specific block by its number.

    ```bash theme={null}
    graphman --config <CONFIG> chain check-blocks <CHAIN_NAME> by-number <NUMBER> [--delete-duplicates]
    ```

    <ParamField path="NUMBER" type="number" required>
      The block number
    </ParamField>

    <ParamField path="--delete-duplicates" type="boolean">
      Delete all duplicated blocks for the given number and continue
    </ParamField>
  </Tab>

  <Tab title="by-range">
    Check a range of blocks.

    ```bash theme={null}
    graphman --config <CONFIG> chain check-blocks <CHAIN_NAME> by-range [OPTIONS]
    ```

    <ParamField path="-f, --from" type="number">
      Starting block number (omit for open lower bound)
    </ParamField>

    <ParamField path="-t, --to" type="number">
      Ending block number (omit for open upper bound)
    </ParamField>

    <ParamField path="--delete-duplicates" type="boolean">
      Delete all duplicated blocks and continue
    </ParamField>
  </Tab>
</Tabs>

### 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

<CodeGroup>
  ```bash By Hash theme={null}
  graphman --config config.toml chain check-blocks mainnet by-hash 0xd56a9f64c7e696cfeb337791a7f4a9e81841aaf4fcad69f9bf2b2e50ad72b972
  ```

  ```bash By Number theme={null}
  graphman --config config.toml chain check-blocks mainnet by-number 15626962
  ```

  ```bash Range with Duplicates theme={null}
  graphman --config config.toml chain check-blocks mainnet by-range --from 15626900 --to 15626962 --delete-duplicates
  ```

  ```bash Open Range theme={null}
  # Check all blocks from 13000000 onwards
  graphman --config config.toml chain check-blocks mainnet by-range --from 13000000
  ```
</CodeGroup>

***

## Call Cache Remove

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

<Warning>
  Removing the entire cache can **significantly reduce indexing performance** and should generally be avoided.
</Warning>

### Usage

```bash theme={null}
graphman --config <CONFIG> chain call-cache <CHAIN_NAME> remove [OPTIONS]
```

### Arguments

<ParamField path="CHAIN_NAME" type="string" required>
  The name of the chain
</ParamField>

### Options

<ParamField path="--remove-entire-cache" type="boolean">
  Remove the entire call cache for the chain
</ParamField>

<ParamField path="--ttl-days" type="number">
  Remove stale contracts not accessed in this many days (based on `call_meta.accessed_at`)
</ParamField>

<ParamField path="--ttl-max-contracts" type="number">
  Limit the number of contracts to consider for stale removal
</ParamField>

<ParamField path="-f, --from" type="number">
  Starting block number for range-based removal
</ParamField>

<ParamField path="-t, --to" type="number">
  Ending block number for range-based removal
</ParamField>

### Removal Strategies

<AccordionGroup>
  <Accordion title="Range-Based Removal">
    Remove cache entries for a specific block range:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="TTL-Based Removal">
    Remove cache entries for contracts that haven't been accessed recently:

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Complete Removal">
    Remove the entire call cache:

    ```bash theme={null}
    graphman --config config.toml chain call-cache ethereum remove --remove-entire-cache
    ```

    **Use with caution**: This will significantly impact indexing performance.
  </Accordion>
</AccordionGroup>

### Examples

<CodeGroup>
  ```bash Block Range theme={null}
  graphman --config config.toml chain call-cache ethereum remove --from 10 --to 20
  ```

  ```bash Stale Contracts theme={null}
  graphman --config config.toml chain call-cache ethereum remove --ttl-days 7
  ```

  ```bash With Limit theme={null}
  graphman --config config.toml chain call-cache ethereum remove --ttl-days 7 --ttl-max-contracts 100
  ```

  ```bash Complete Removal theme={null}
  graphman --config config.toml chain call-cache ethereum remove --remove-entire-cache
  ```
</CodeGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Always Use --config" icon="gear">
    Always specify the configuration file path with `--config` to ensure commands operate on the correct Graph Node instance.
  </Card>

  <Card title="Verify Before Dropping" icon="shield-check">
    Use `info` command to verify deployment details before running destructive operations like `drop`.
  </Card>

  <Card title="Two-Step Cleanup" icon="list-check">
    Use `unused record` followed by `unused remove` instead of immediately dropping deployments. This gives you time to verify.
  </Card>

  <Card title="Monitor Block Cache" icon="magnifying-glass">
    Regularly use `check-blocks` to ensure RPC provider data integrity, especially after RPC provider changes.
  </Card>
</CardGroup>

## See Also

* [Graphman GraphQL API](/api/graphman-graphql) - Manage deployments via GraphQL
* [Graph Node Maintenance](https://github.com/graphprotocol/graph-node/blob/master/docs/maintenance.md) - Detailed maintenance procedures