CLI DOCUMENTATION

May 22, 2026 ยท View on GitHub

The CLI is the main interface to interact with aiiinotate: all aiiinotate commands are started from the CLI.

Basics

  1. Have your app set up, either in dev or in prod. See README for more info

  2. In prod, source your .env. See README.

  3. The base command is:

# in prod
aiiinotate

# in dev
npm run cli

The command changes with a prod install, because the package has been installed with npm.

  • for the rest of this doc, we use aiiinotate instead of npm run cli. Use whichever is appropriate to your use case.
  • npm run cli runs a bash script that also manages environment sourcing.
  • when using npm run cli, you will sometimes need to add -- to separate different arguments: 
    npm run cli -- <command> <arguments>

serve: start the app

# serve the app in dev mode
aiiinotate serve dev

# serve the app in prod mode
aiiinotate serve prod

migrate: run database migrations

NOTE: in dev, run npm run migrate, which is a wrapper for npm run cli migrate.

# create a new migration
aiiinotate migrate make --migration-name <your migration name>
# the equivalent in dev is:
npm run migrate make -- --migration-name <your migration name>

# apply all pending migrations
aiiinotate migrate apply

# revert the last migration
aiiinotate migrate revert

# revert all migrations
aiiinotate migrate revert-all

import: import data

The CLI can be used to import IIIF annotations or to index IIIF manifests in aiiinotate.

aiiinotate import <manifests|annotations> -i 2 -f <path/to/import/file.txt>

Where:

  • <manifests|annotations> is the kind of data to import: manifests or annotations
  • -i --iiif-version (2|3) is the IIIF Presentation API version of the data to import:
    • if -i 3, we import IIIF presentation 3.x data
    • if -i 2, we import IIIF presentation 2.x data
  • -f --file is a relative or absolute path the the import file. This import file:
    • contains a list of paths to annotation lists, annotation pages or manifests
    • with 1 path per line
    • paths can be relative or absolute

NOTE that data to import MUST MATCH the IIIF version: if -i 2, you can only import AnnotationLists following the IIIF Presentation 2.x standard, and note annotations in 3.x format.

NOTE that for the moment, import is only implemented for IIIF version 2.

Here is an example of import file:

./annotations/wit91_pdf108_anno194.json
./annotations/wit70_man70_anno206.json
./annotations/wit71_man71_anno202.json
./annotations/wit68_man68_anno198.json
./annotations/wit72_man72_anno133.json
./annotations/wit75_man74_anno130.json
./annotations/wit2_man4_anno4.json

export: export data

The CLI can be used to export data to JSON.

aiiinotate export <all|annotations2|manifests2|annotations3|manifests3> [-o /output/dir]?

Each collection will be written to its own JSON file.

Exported JSON data can be imported back in a MongoDB instance using mongoimport:

 mongoimport \
   --host localhost \
   --db <db name> \
   --collection <collection name> \
   --file <./path/to/export.json> \
   --jsonArray

xywhToInt

In versions of aiiinotate >0.10.3, the xywh bounding box extracted from incoming annotations and saved to database may contain floats. This causes errors when reconstructing Cantaloupe URLs from txywh. This command converts all xywh containing floats to intgers. It is only implemented for collection annotations2.

aiiinotate run xywh-to-int