---
title: "Importing entries from the command line with WP-CLI"
date: 2026-08-27
author: "Rafael Bennemann"
link: "https://www.gravitykit.com/docs/gravityimport/import-entries-with-wp-cli/"
---

GravityImport 2.11.0 and later can run an import from the command line. This suits large files and scripted or scheduled imports: the command works through the whole file in one process, prints its progress as it goes, and finishes only when the import is done. There is no browser tab to leave open.

## Before you start

You need WP-CLI access to the site, GravityImport 2.11.0 or later, and an import profile saved from a previous import. The profile carries the field mapping and the import options, so the command does not need to ask you anything.

## Saving an import profile

Run an import through the importer once, mapping your columns to the form fields as usual. On the **Import Complete** screen at the end, click **Download Import Profile** to save that mapping as a JSON file, then put the file somewhere the command can reach it on the server. See [Mapping CSV columns to form fields](https://www.gravitykit.com/docs/gravityimport/map-csv-to-form-fields/) for the mapping step itself.

![Import Complete screen with the Download Import Profile button highlighted, labelled as the button that saves the profile the CLI needs](https://www.gravitykit.com/wp-content/uploads/2026/08/gravityimport-download-import-profile-annotated.png)

## Running an import

Pass the CSV file and the profile:

```
wp gk import run --file=data.csv --profile=profile.json
```

```
wp gk import run --file=data.csv --profile=profile.json
```

The command creates the import batch, then processes it to the end and prints a summary. On a longer file it also reports how many rows it has handled as it works.

```
Creating import batch for Form #123...
Batch #559 created. Processing...
Status: done
Success: Import complete: 5 entries imported from 5 rows.
```

```
Creating import batch for Form #123...
Batch #559 created. Processing...
Status: done
Success: Import complete: 5 entries imported from 5 rows.
```

These options are available:

| Option | What it does |
|---|---|
| `--file` | Path to the CSV file to import. Required. |
| `--profile` | Path to the import profile JSON file. Required. |
| `--form-id` | Import into a different form than the one saved in the profile. |
| `--dry-run` | Report what the import would do without creating a batch or importing anything. |
| `--force` | Continue even though the form has changed since the profile was saved. |
| `--format` | Output format: `table` (the default), `json`, `csv`, or `yaml`. |

## Checking a profile before you run it

To check that a profile still fits a CSV file and a form without importing anything:

```
wp gk import validate --file=data.csv --profile=profile.json
```

```
wp gk import validate --file=data.csv --profile=profile.json
```

```
Profile structure is valid.
Form #123 exists: CLI Doc Members
Form structure matches profile.
Column matching: 5 matched, 0 unmatched.
5 schema rules mapped successfully.
Success: Profile validation complete.
```

```
Profile structure is valid.
Form #123 exists: CLI Doc Members
Form structure matches profile.
Column matching: 5 matched, 0 unmatched.
5 schema rules mapped successfully.
Success: Profile validation complete.
```

This confirms that the profile is readable and that the form exists, says whether the form still matches the profile, and reports how many CSV columns were matched and how many were not. Adding `--dry-run` to the run command gives a similar summary of the import itself.

## When the form has changed

A profile records the structure of the form it was saved against. If fields have been added, removed, or reordered since then, the run command stops with the message *Form structure has changed since profile was saved. Use --force to proceed anyway.*

```
Error: Form structure has changed since profile was saved. Use --force to proceed anyway.
```

```
Error: Form structure has changed since profile was saved. Use --force to proceed anyway.
```

The validate command reports the same thing as a warning and carries on, which makes it a safe way to check a profile before a scheduled job depends on it.

**Warning**: `--force` imports with a mapping built for the older version of the form, so columns can land in the wrong fields. Validate the profile first, and save a fresh one if the mapping no longer fits.

## Scripting around the command

Both commands accept `--format=json`, which replaces the readable output with a single structured record. This is the easier form to parse in a deployment script or a scheduled job.

```
wp gk import run --file=data.csv --profile=profile.json --format=json
```

```
wp gk import run --file=data.csv --profile=profile.json --format=json
```