> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/iagctl/db-import/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# iagctl db import

Import resources and services from a file.

The `iagctl db import` command imports services and resources from a service configuration file. Use this command to move services and resources from one gateway instance to another, or to import a file you've created manually.

You can import from a local file or from a repository. Gateway also provides the `--validate` and `--check` flags to verify the import before applying changes.

## Syntax

```bash
iagctl db import <filename> [flags]
```

## Usage notes

### Validate an import

Use the `--validate` flag to verify that all resources in the file contain the required fields. If any fields are missing, the gateway returns details so you can resolve the issue.

### Preview an import

Use the `--check` flag to preview the actions the gateway would take without making any changes. The gateway reports one of three states for each resource:

| State       | Description                                                                                                       |
| :---------- | :---------------------------------------------------------------------------------------------------------------- |
| Conflict    | A resource with the same name already exists. The gateway takes no action unless you also use the `--force` flag. |
| Add         | The resource is new and the gateway creates it on import.                                                         |
| Replacement | The resource replaces an existing one. This state appears when you combine `--check` with `--force`.              |

### Force an import

Use the `--force` flag to override any existing resources that conflict with the imported file.

## Examples

### Import from a local file

```bash
iagctl db import ./file.yml
```

### Import from a repository over HTTP

```bash
iagctl db import --repository https://github.com/itential/quick.git import.yml
```

### Import from a repository over SSH with a private key

```bash
iagctl db import --repository git@github.com:itential/quick.git \
--private-key-name my-private-key import.yml
```

### Validate a service file

```bash
iagctl db import ./file.yml --validate
```

### Preview an import

```bash
iagctl db import ./file.yml --check
```

### Preview a forced import

```bash
iagctl db import ./file.yml --check --force
```

### Service file format

The following example shows the structure of a service configuration file:

```yml
decorators:
  - name: ansible-xr
    schema:
      $id: https://example.com/device.schema.json
      $schema: https://json-schema.org/draft/2020-12/schema
      properties:
        device_type:
          description: The type of device
          enum:
            - ios
            - eos
            - nxos
          type: string
        host:
          description: The hostname or IP address of the device
          type: string
      title: Network Device
      type: object
repositories:
  - name: xr-resources
    description: XR Resources for testing
    url: git@gitlab.com:jh/xr/resources.git
    reference: main
    tags:
      - cisco
      - xr
    private-key-name: xr-gitlab-private
services:
  - name: Ansible-Example
    type: ansible-playbook
    description: An ansible playbook to say hello-world
    playbooks:
      - hello-world.yml
    working-directory: ./
    repository: xr-resources
    decorator: ansible-xr
    tags:
      - xr
      - cisco
    runtime:
      check: true
      diff: true
      skip-tags: example-tag
      inventory:
        - ./inventory.ini
      verbose-level: 6
  - name: Hello-World
    type: python-script
    description: A simple hello-world playbook
    filename: hello-world.py
    working-directory: python-scripts
    repository: xr-resources
    decorator: my-special-decorator
```

## Options

```bash
  --check                 Validate and preview the import without making changes.
  --force                 Override any existing resources that conflict with the import.
  -h, --help              Help for import
  --repository string     The repository to import from. Must be a preconfigured repository referenced by name.
  --validate              Validate the service file without importing.
```

## Options inherited from parent commands

```bash
  --profile string   Specify the client profile to use (case-insensitive, defaults to [client] section)
  --config string   Path to the configuration file
  --raw             Display the result of the command in raw format
  --verbose         Enable verbose output
```