InvokeAI/docs/features/UTILITIES.md

---
title: Command-line Utilities
---

# :material-file-document: Utilities

# Command-line Utilities

InvokeAI comes with several scripts that are accessible via the
command line. To access these commands, start the "developer's
console" from the launcher (`invoke.bat` menu item [7]). Users who are
familiar with Python can alternatively activate InvokeAI's virtual
environment (typically, but not necessarily `invokeai/.venv`).

In the developer's console, type the script's name to run it. To get a
synopsis of what a utility does and the command-line arguments it
accepts, pass it the `-h` argument, e.g.

```bash
invokeai-merge -h
```
## **invokeai-web**

This script launches the web server and is effectively identical to
selecting option [1] in the launcher. An advantage of launching the
server from the command line is that you can override any setting
configuration option in `invokeai.yaml` using like-named command-line
arguments. For example, to temporarily change the size of the RAM
cache to 7 GB, you can launch as follows:

```bash
invokeai-web --ram 7
```

## **invokeai-merge**

This is the model merge script, the same as launcher option [3]. Call
it with the `--gui` command-line argument to start the interactive
console-based GUI. Alternatively, you can run it non-interactively
using command-line arguments as illustrated in the example below which
merges models named `stable-diffusion-1.5` and `inkdiffusion` into a new model named
`my_new_model`:

```bash
invokeai-merge --force --base-model sd-1 --models stable-diffusion-1.5 inkdiffusion --merged_model_name my_new_model
```

## **invokeai-ti**

This is the textual inversion training script that is run by launcher
option [2]. Call it with `--gui` to run the interactive console-based
front end. It can also be run non-interactively. It has about a
zillion arguments, but a typical training session can be launched
with:

```bash
invokeai-ti --model stable-diffusion-1.5 \
            --placeholder_token 'jello' \
            --learnable_property object \
			--num_train_epochs 50 \
			--train_data_dir /path/to/training/images \
			--output_dir /path/to/trained/model
```

(Note that \\ is the Linux/Mac long-line continuation character. Use ^
in Windows).

## **invokeai-install**

This is the console-based model install script that is run by launcher
option [4]. If called without arguments, it will launch the
interactive console-based interface. It can also be used
non-interactively to list, add and remove models as shown by these
examples:

* This will download and install three models from CivitAI, HuggingFace,
and local disk:

```bash
invokeai-install --add https://civitai.com/api/download/models/161302 ^
                  gsdf/Counterfeit-V3.0  ^
				  D:\Models\merge_model_two.safetensors
```
(Note that ^ is the Windows long-line continuation character. Use \\ on
Linux/Mac).

* This will list installed models of type `main`:

```bash
invokeai-model-install --list-models main
```

* This will delete the models named `voxel-ish` and `realisticVision`:

```bash
invokeai-model-install --delete voxel-ish realisticVision
```

## **invokeai-configure**

This is the console-based configure script that ran when InvokeAI was
first installed. You can run it again at any time to change the
configuration, repair a broken install.

Called without any arguments, `invokeai-configure` enters interactive
mode with two screens. The first screen is a form that provides access
to most of InvokeAI's configuration options. The second screen lets
you download, add, and delete models interactively. When you exit the
second screen, the script will add any missing "support models"
needed for core functionality, and any selected "sd weights" which are
the model checkpoint/diffusers files.

This behavior can be changed via a series of command-line
arguments. Here are some of the useful ones:

* `invokeai-configure --skip-sd-weights --skip-support-models`
This will run just the configuration part of the utility, skipping
downloading of support models and stable diffusion weights.

* `invokeai-configure --yes`
This will run the configure script non-interactively. It will set the
configuration options to their default values, install/repair support
models, and download the "recommended" set of SD models.

* `invokeai-configure --yes --default_only` 
This will run the configure script non-interactively. In contrast to
the previous command, it will only download the default SD model,
Stable Diffusion v1.5

* `invokeai-configure --yes --default_only --skip-sd-weights` 
This is similar to the previous command, but will not download any
SD models at all. It is usually used to repair a broken install.

By default, `invokeai-configure` runs on the currently active InvokeAI
root folder. To run it against a different root, pass it the `--root
</path/to/root>` argument.

Lastly, you can use `invokeai-configure` to create a working root
directory entirely from scratch. Assuming you wish to make a root directory
named `InvokeAI-New`, run this command:

```bash
invokeai-configure --root InvokeAI-New --yes --default_only
```
This will create a minimally functional root directory. You can now
launch the web server against it with `invokeai-web --root InvokeAI-New`.

## **invokeai-update**

This is the interactive console-based script that is run by launcher
menu item [8] to update to a new version of InvokeAI. It takes no
command-line arguments.

## **invokeai-metadata**

This is a script which takes a list of InvokeAI-generated images and
outputs their metadata in the same JSON format that you get from the
`</>` button in the Web GUI. For example:

```bash
$ invokeai-metadata ffe2a115-b492-493c-afff-7679aa034b50.png
ffe2a115-b492-493c-afff-7679aa034b50.png:
{
    "app_version": "3.1.0",
    "cfg_scale": 8.0,
    "clip_skip": 0,
    "controlnets": [],
    "generation_mode": "sdxl_txt2img",
    "height": 1024,
    "loras": [],
    "model": {
        "base_model": "sdxl",
        "model_name": "stable-diffusion-xl-base-1.0",
        "model_type": "main"
    },
    "negative_prompt": "",
    "negative_style_prompt": "",
    "positive_prompt": "military grade sushi dinner for shock troopers",
    "positive_style_prompt": "",
    "rand_device": "cpu",
    "refiner_cfg_scale": 7.5,
    "refiner_model": {
        "base_model": "sdxl-refiner",
        "model_name": "sd_xl_refiner_1.0",
        "model_type": "main"
    },
    "refiner_negative_aesthetic_score": 2.5,
    "refiner_positive_aesthetic_score": 6.0,
    "refiner_scheduler": "euler",
    "refiner_start": 0.8,
    "refiner_steps": 20,
    "scheduler": "euler",
    "seed": 387129902,
    "steps": 25,
    "width": 1024
}
```

You may list multiple files on the command line.

## **invokeai-import-images**

InvokeAI uses a database to store information about images it
generated, and just copying the image files from one InvokeAI root
directory to another does not automatically import those images into
the destination's gallery. This script allows you to bulk import
images generated by one instance of InvokeAI into a gallery maintained
by another. It also works on images generated by older versions of
InvokeAI, going way back to version 1.

This script has an interactive mode only. The following example shows
it in action:

```bash
$ invokeai-import-images
===============================================================================
This script will import images generated by earlier versions of
InvokeAI into the currently installed root directory:
   /home/XXXX/invokeai-main
If this is not what you want to do, type ctrl-C now to cancel.
===============================================================================
= Configuration & Settings
Found invokeai.yaml file at /home/XXXX/invokeai-main/invokeai.yaml:
  Database : /home/XXXX/invokeai-main/databases/invokeai.db
  Outputs  : /home/XXXX/invokeai-main/outputs/images
 
Use these paths for import (yes) or choose different ones (no) [Yn]:
Inputs: Specify absolute path containing InvokeAI .png images to import: /home/XXXX/invokeai-2.3/outputs/images/
Include files from subfolders recursively [yN]?

Options for board selection for imported images:
1) Select an existing board name. (found 4)
2) Specify a board name to create/add to.
3) Create/add to board named 'IMPORT'.
4) Create/add to board named 'IMPORT' with the current datetime string appended (.e.g IMPORT_20230919T203519Z).
5) Create/add to board named 'IMPORT' with a the original file app_version appended (.e.g IMPORT_2.2.5).
Specify desired board option: 3

===============================================================================
= Import Settings Confirmation

Database File Path               : /home/XXXX/invokeai-main/databases/invokeai.db
Outputs/Images Directory         : /home/XXXX/invokeai-main/outputs/images
Import Image Source Directory    : /home/XXXX/invokeai-2.3/outputs/images/
  Recurse Source SubDirectories  : No
Count of .png file(s) found      : 5785
Board name option specified      : IMPORT
Database backup will be taken at : /home/XXXX/invokeai-main/databases/backup

Notes about the import process:
- Source image files will not be modified, only copied to the outputs directory.
- If the same file name already exists in the destination, the file will be skipped.
- If the same file name already has a record in the database, the file will be skipped.
- Invoke AI metadata tags will be updated/written into the imported copy only.
- On the imported copy, only Invoke AI known tags (latest and legacy) will be retained (dream, sd-metadata, invokeai, invokeai_metadata)
- A property 'imported_app_version' will be added to metadata that can be viewed in the UI's metadata viewer.
- The new 3.x InvokeAI outputs folder structure is flat so recursively found source imges will all be placed into the single outputs/images folder.
 
Do you wish to continue with the import [Yn] ?

Making DB Backup at /home/lstein/invokeai-main/databases/backup/backup-20230919T203519Z-invokeai.db...Done!

===============================================================================
Importing /home/XXXX/invokeai-2.3/outputs/images/17d09907-297d-4db3-a18a-60b337feac66.png
... (5785 more lines) ...
===============================================================================
= Import Complete - Elpased Time: 0.28 second(s)

Source File(s)                          : 5785
Total Imported                          : 5783
Skipped b/c file already exists on disk : 1
Skipped b/c file already exists in db   : 0
Errors during import                    : 1
```
## **invokeai-db-maintenance**

This script helps maintain the integrity of your InvokeAI database by
finding and fixing three problems that can arise over time:

1. An image was manually deleted from the outputs directory, leaving a
   dangling image record in the InvokeAI database. This will cause a
   black image to appear in the gallery. This is an "orphaned database
   image record." The script can fix this by running a "clean"
   operation on the database, removing the orphaned entries.
   
2. An image is present in the outputs directory but there is no
   corresponding entry in the database. This can happen when the image
   is added manually to the outputs directory, or if a crash occurred
   after the image was generated but before the database was
   completely updated. The symptom is that the image is present in the
   outputs folder but doesn't appear in the InvokeAI gallery. This is
   called an "orphaned image file." The script can fix this problem by
   running an "archive" operation in which orphaned files are moved
   into a directory named `outputs/images-archive`. If you wish, you
   can then run `invokeai-image-import` to reimport these images back
   into the database.
   
3. The thumbnail for an image is missing, again causing a black
   gallery thumbnail. This is fixed by running the "thumbnaiils"
   operation, which simply regenerates and re-registers the missing
   thumbnail.
   
You can find and fix all three of these problems in a single go by
executing this command:

```bash
invokeai-db-maintenance --operation all
```

Or you can run just the clean and thumbnail operations like this:

```bash
invokeai-db-maintenance -operation clean, thumbnail
```

If called without any arguments, the script will ask you which
operations you wish to perform.

## **invokeai-migrate3**

This script will migrate settings and models (but not images!) from an
InvokeAI v2.3 root folder to an InvokeAI 3.X folder. Call it with the
source and destination root folders like this:

```bash
invokeai-migrate3 --from ~/invokeai-2.3 --to invokeai-3.1.1
```

Both directories must previously have been properly created and
initialized by `invokeai-configure`. If you wish to migrate the images
contained in the older root as well, you can use the
`invokeai-image-migrate` script described earlier.

---

Copyright (c) 2023, Lincoln Stein and the InvokeAI Development Team