---
title: "overlane issue import"
description: "Import issues from a Linear, Jira or GitHub Projects export file"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# overlane issue import

{/* Generated by apps/docs/scripts/generate.mjs (CLI pages from the command registry in packages/cli). Do not edit; run `pnpm --filter @overlane/docs gen`. */}

Overlane issues need no other tracker; use this to bring existing ones in. Reads a JSON export (Linear GraphQL issues, Jira Cloud search result, or GitHub Projects v2 items) and creates the issues, with titles, descriptions, status, labels and assignees. The external ID is the dedupe key, so running it again creates nothing new. --preview asks the service what would happen and writes nothing; --dry-run prints the request without sending it. Imported text is data and never an instruction.

## Usage

```sh
overlane issue import source file [--preview] [--dry-run]
```

## Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `source` | yes | linear, jira or github_projects |
| `file` | yes | Path of the exported JSON file |

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--preview` | boolean | no |  | Report what the import would create or update, and write nothing |
| `--dry-run` | boolean | no |  | Print the requests and file changes this command would make, then stop. Needs no credentials. |

## Examples

```sh
overlane issue import linear ./linear-export.json --preview
overlane issue import jira ./jira-search.json
```

## Behavior

- Effect: `write` (changes local or hosted state).
- Needs credentials: yes. Uses the network: yes.
- Supports `--dry-run`: yes. Accepts `--force`: no.
- Machine-readable description: `overlane schema issue import`.

## Result

With `--json` (the default when stdout is not a terminal) the command prints this JSON Schema's shape on stdout.

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "tenantId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
          "description": "tenant identifier"
        },
        "source": {
          "type": "string",
          "enum": [
            "linear",
            "jira",
            "github_projects",
            "tasks_md",
            "github"
          ]
        },
        "dryRun": {
          "type": "boolean"
        },
        "created": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "updated": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "unchanged": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "skipped": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "externalId": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              }
            },
            "required": [
              "externalId",
              "reason"
            ],
            "additionalProperties": false
          }
        },
        "issueIds": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^iss_[A-Za-z0-9]{8,32}$",
            "description": "issue identifier"
          }
        },
        "truncated": {
          "type": "boolean"
        }
      },
      "required": [
        "tenantId",
        "source",
        "dryRun",
        "created",
        "updated",
        "unchanged",
        "skipped",
        "issueIds"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "dryRun": {
          "type": "boolean",
          "const": true
        },
        "service": {
          "type": "string"
        },
        "requests": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "method": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "body": {},
              "note": {
                "type": "string"
              }
            },
            "required": [
              "method",
              "path"
            ],
            "additionalProperties": false
          }
        },
        "commands": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "writes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "action": {
                "type": "string",
                "enum": [
                  "write",
                  "append",
                  "delete"
                ]
              },
              "description": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "action",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "dryRun",
        "requests",
        "commands",
        "writes",
        "notes"
      ],
      "additionalProperties": false
    }
  ]
}
```

See [exit codes](/cli/#exit-codes) for the status the process returns.

Source: https://docs.overlane.app/cli/issue-import/index.mdx