Skip to content

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.

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:

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:

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:

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:

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:
invokeai-model-install --list-models main
  • This will delete the models named voxel-ish and realisticVision:
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:

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:

$ 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:

$ 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:

invokeai-db-maintenance --operation all

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

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:

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 © 2023, Lincoln Stein and the InvokeAI Development Team