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

> Command-line tool for managing Graph Node deployments

Graphman is a powerful command-line tool included with Graph Node for managing subgraph deployments, performing maintenance operations, and troubleshooting issues.

## Getting Started

Graphman is included in the official Graph Node containers. You can access it by running:

```bash theme={null}
docker exec -it <graph-node-container> graphman --config config.toml <command>
```

<Note>
  Graphman requires a [configuration file](/configuration/config-file) to connect to your Graph Node infrastructure. If you don't have one, follow the [basic setup instructions](/configuration/config-file#basic-setup) to create a minimal configuration.
</Note>

### Environment Variables

Graphman respects the `GRAPH_LOG` environment variable for logging output. To disable logs:

```bash theme={null}
unset GRAPH_LOG
graphman --config config.toml <command>
```

### Verifying Setup

Test that graphman is configured correctly:

```bash theme={null}
graphman --config config.toml info some/subgraph
```

If successful, this will display basic information about the deployment, including its database namespace.

## Core Commands

### Info

Prints detailed information about a deployment.

**Synopsis:**

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

**Arguments:**

* `<DEPLOYMENT>` - The deployment identifier (subgraph name, IPFS hash `Qm..`, or database namespace `sgdNNN`)

**Options:**

* `-c, --current` - List only current version
* `-p, --pending` - List only pending versions
* `-u, --used` - List only used (current and pending) versions
* `-s, --status` - Include status information

**Output Fields:**

By default, the info command displays:

* **name** - The subgraph name
* **status** - Either `pending` or `current`
* **id** - The `Qm...` IPFS identifier
* **namespace** - Database schema containing deployment tables
* **shard** - Database shard location
* **active** - Whether this version is used for queries
* **chain** - The blockchain network
* **graph node id** - The assigned node instance

With `--status` enabled, additional fields include:

* **synced** - Whether synced to current chain head
* **health** - `healthy`, `unhealthy`, or `failed`
* **latest indexed block** - Most recent processed block
* **current chain head block** - Latest blockchain block

**Examples:**

<Accordion title="Query by name">
  ```bash theme={null}
  graphman --config config.toml info subgraph-name
  ```
</Accordion>

<Accordion title="Query by IPFS hash">
  ```bash theme={null}
  graphman --config config.toml info QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
  ```
</Accordion>

<Accordion title="Query with status information">
  ```bash theme={null}
  graphman --config config.toml info QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66 --status
  ```
</Accordion>

### Remove

Removes the association between a subgraph name and its deployment.

**Synopsis:**

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

**Arguments:**

* `<NAME>` - The name of the subgraph to remove

<Note>
  This command does not delete indexed data. It only removes the name mapping, stopping query traffic to that name and freeing it for reuse.
</Note>

**Example:**

```bash theme={null}
graphman --config config.toml remove subgraph-name
```

### Unassign

Stops Graph Node from indexing a deployment permanently.

**Synopsis:**

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

**Arguments:**

* `<DEPLOYMENT>` - The deployment identifier

<Note>
  No indexed data is lost. The deployment remains in the database but stops receiving updates. See [Maintenance Operations](/operations/maintenance#modifying-assignments) for more details on assignment management.
</Note>

**Examples:**

<Accordion title="Unassign by name">
  ```bash theme={null}
  graphman --config config.toml unassign subgraph-name
  ```
</Accordion>

<Accordion title="Unassign by IPFS hash">
  ```bash theme={null}
  graphman --config config.toml unassign QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
  ```
</Accordion>

### Drop

Completely deletes a deployment and all its indexed data.

**Synopsis:**

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

**Arguments:**

* `<DEPLOYMENT>` - The deployment identifier

**Options:**

* `-c, --current` - Search only for current versions
* `-p, --pending` - Search only for pending versions
* `-u, --used` - Search only for used versions
* `-f, --force` - Skip confirmation prompt

<Warning>
  This operation is irreversible. The drop command executes these steps in sequence:

  <Steps>
    <Step title="Query deployment info">
      Runs `graphman info <deployment>` to identify the deployment
    </Step>

    <Step title="Unassign deployment">
      Runs `graphman unassign <deployment>` to stop indexing
    </Step>

    <Step title="Remove name mapping">
      Runs `graphman remove <name>` to free the subgraph name
    </Step>

    <Step title="Mark as unused">
      Runs `graphman unused record` to register for deletion
    </Step>

    <Step title="Delete data">
      Runs `graphman unused remove <deployment>` to purge all data
    </Step>
  </Steps>
</Warning>

**Examples:**

<Accordion title="Drop by deployment ID">
  ```bash theme={null}
  graphman --config config.toml drop QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
  ```
</Accordion>

<Accordion title="Drop by subgraph name">
  ```bash theme={null}
  graphman --config config.toml drop author/subgraph-name
  ```
</Accordion>

## Cleanup Commands

### Unused Record

Scans all shards for unused deployments and registers them for removal.

**Synopsis:**

```bash theme={null}
graphman unused record
```

**Description:**

Identifies deployments that meet all these criteria:

1. Not assigned to any node
2. Either not marked as active, or neither current nor pending version of a subgraph
3. Not the source of a currently running copy operation

Recorded deployments are stored in the `unused_deployments` table in the primary shard.

<Note>
  This command does not delete any data. It only marks deployments for future removal.
</Note>

**Example:**

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

### Unused Remove

Deletes deployments previously marked as unused.

**Synopsis:**

```bash theme={null}
graphman unused remove [OPTIONS]
```

**Options:**

* `-c, --count <COUNT>` - How many unused deployments to remove (default: all)
* `-d, --deployment <DEPLOYMENT>` - Remove a specific deployment
* `-o, --older <OLDER>` - Remove only deployments recorded at least this many minutes ago

<Warning>
  This operation is irreversible. All indexed data for removed deployments is permanently deleted.
</Warning>

Deployments are removed in descending order by entity count (smaller deployments first).

**Examples:**

<Accordion title="Remove all unused deployments">
  ```bash theme={null}
  graphman --config config.toml unused remove
  ```
</Accordion>

<Accordion title="Remove deployments older than 12 hours">
  ```bash theme={null}
  graphman --config config.toml unused remove --older 720
  ```
</Accordion>

<Accordion title="Remove specific deployment">
  ```bash theme={null}
  graphman --config config.toml unused remove --deployment QmfWRZCjT8pri4Amey3e3mb2Bga75Vuh2fPYyNVnmPYL66
  ```
</Accordion>

## Chain Management

### Check Blocks

Validates cached blocks against fresh data from the JSON RPC provider.

**Synopsis:**

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

**Arguments:**

* `<chain-name>` - Chain name (must be configured in your config file)

**Subcommands:**

* `by-hash <hash>` - Check a single block by hash
* `by-number <number>` - Check a single block by number
* `by-range [--from <n>] [--to <n>]` - Check a range of blocks

**Options for by-number and by-range:**

* `--delete-duplicates` - Automatically remove duplicate blocks at the same height

**Description:**

JSON RPC providers sometimes send invalid block data to Graph Node. This command compares cached blocks with fresh data from the provider and removes any mismatches.

When multiple blocks exist for the same block number, graphman will abort unless `--delete-duplicates` is specified, which removes all duplicates for that block number.

**Examples:**

<Accordion title="Check single block by hash">
  ```bash theme={null}
  graphman --config config.toml chain check-blocks mainnet by-hash 0xd56a9f64c7e696cfeb337791a7f4a9e81841aaf4fcad69f9bf2b2e50ad72b972
  ```
</Accordion>

<Accordion title="Check single block by number">
  ```bash theme={null}
  graphman --config config.toml chain check-blocks mainnet by-number 15626962
  ```
</Accordion>

<Accordion title="Check block range with duplicate removal">
  ```bash theme={null}
  graphman --config config.toml chain check-blocks mainnet by-range --from 15626900 --to 15626962 --delete-duplicates
  ```
</Accordion>

<Accordion title="Check all blocks after specific height">
  ```bash theme={null}
  graphman --config config.toml chain check-blocks mainnet by-range --from 13000000
  ```
</Accordion>

### Call Cache Remove

Removes call cache entries for a specified chain.

**Synopsis:**

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

**Options:**

* `--from <FROM>` - Starting block number
* `--to <TO>` - Ending block number
* `--remove-entire-cache` - Remove the complete cache
* `--ttl-days <TTL_DAYS>` - Remove contracts not accessed for this many days
* `--ttl-max-contracts <MAX>` - Limit number of contracts removed with TTL

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

**Block Range Options:**

When using `--from` and `--to`:

* Omitting `--from` starts from the first cached block
* Omitting `--to` extends to the last cached block

**TTL-Based Removal:**

The `--ttl-days` option removes stale contracts based on the `call_meta.accessed_at` field. For example, `--ttl-days 7` removes all calls to contracts not accessed in the last 7 days.

Use `--ttl-max-contracts` to limit how many contracts are removed in a single operation.

**Examples:**

<Accordion title="Remove cache for block range">
  ```bash theme={null}
  graphman --config config.toml chain call-cache ethereum remove --from 10 --to 20
  ```
</Accordion>

<Accordion title="Remove entire cache">
  ```bash theme={null}
  graphman --config config.toml chain call-cache ethereum remove --remove-entire-cache
  ```
</Accordion>

<Accordion title="Remove stale contracts (7 days)">
  ```bash theme={null}
  graphman --config config.toml chain call-cache ethereum remove --ttl-days 7
  ```
</Accordion>

<Accordion title="Remove stale contracts with limit">
  ```bash theme={null}
  graphman --config config.toml chain call-cache ethereum remove --ttl-days 7 --ttl-max-contracts 100
  ```
</Accordion>

## Workflow Examples

### Typical Cleanup Workflow

When you need to free up disk space by removing old deployments:

<Steps>
  <Step title="Identify unused deployments">
    ```bash theme={null}
    graphman --config config.toml unused record
    ```

    This scans all shards and marks unused deployments.
  </Step>

  <Step title="Review what will be removed">
    ```bash theme={null}
    graphman --config config.toml unused list -e
    ```

    Inspect the list of deployments marked for removal.
  </Step>

  <Step title="Remove unused deployments">
    ```bash theme={null}
    graphman --config config.toml unused remove
    ```

    Permanently delete the indexed data for unused deployments.
  </Step>
</Steps>

### Migrating a Deployment

To stop serving a subgraph and free its name for a new version:

<Steps>
  <Step title="Remove the name mapping">
    ```bash theme={null}
    graphman --config config.toml remove author/subgraph-name
    ```

    This stops query traffic to the old version.
  </Step>

  <Step title="Record as unused">
    ```bash theme={null}
    graphman --config config.toml unused record
    ```

    Mark the old deployment for cleanup.
  </Step>

  <Step title="Deploy new version">
    Deploy your new subgraph version. It can now use the freed name.
  </Step>

  <Step title="Clean up old data">
    ```bash theme={null}
    graphman --config config.toml unused remove
    ```

    Remove the old deployment data after confirming the new version works.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Always test graphman commands">
    Before running destructive commands like `drop` or `unused remove`, use `info` and `unused list` to verify which deployments will be affected.
  </Accordion>

  <Accordion title="Use --force carefully">
    The `--force` flag skips confirmation prompts. Only use it in automated scripts after thorough testing.
  </Accordion>

  <Accordion title="Wait before removing unused deployments">
    Use `--older` with `unused remove` to ensure deployments have been unused for a safe period (e.g., 24 hours) before deletion.
  </Accordion>

  <Accordion title="Monitor block cache health">
    Regularly run `check-blocks` on critical block ranges to ensure data integrity, especially after RPC provider changes.
  </Accordion>

  <Accordion title="Clean call cache strategically">
    Use TTL-based removal instead of clearing the entire cache to maintain indexing performance.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Graphman can't connect to database

Ensure your config file has correct database connection strings and that the database is accessible from the container.

### Deployment not found

Verify the deployment identifier using:

```bash theme={null}
graphman --config config.toml info <deployment>
```

Try different identifier formats (name, IPFS hash, namespace).

### Check-blocks finds mismatches

This indicates your RPC provider sent incorrect data. The command automatically removes bad cached blocks. Consider switching to a more reliable RPC provider.

### Unused remove doesn't delete a deployment

Ensure the deployment was marked as unused with `graphman unused record` first. Check that it's not currently assigned to a node.