CLI commands

These are the command-line interface commands of Annif, with REST API equivalents when applicable.

To reference a vocabulary or a project, most of the commands take either a VOCAB_ID or a PROJECT_ID parameter, which are alphanumeric strings (A-Za-z0-9_-). Common options of the commands are --projects for setting a (non-default) path to a project configuration file and --verbosity for selecting logging level.

Vocabulary administration

annif load-vocab

Load a vocabulary from a subject file.

annif load-vocab [OPTIONS] VOCAB_ID SUBJECTFILE

Options

-L, --language <language>

Language of subject file

-f, --force

Replace existing vocabulary completely instead of updating it

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

VOCAB_ID

Required argument

SUBJECTFILE

Required argument

REST equivalent

N/A

annif list-vocabs

List available vocabularies.

annif list-vocabs [OPTIONS]

Options

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

REST equivalent

N/A

Project administration

annif list-projects

List available projects.

Show a list of currently defined projects. Projects are defined in a configuration file, normally called projects.cfg. See Project configuration for details.

annif list-projects [OPTIONS]

Options

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

REST equivalent

GET /projects/

annif show-project

Show information about a project.

annif show-project [OPTIONS] PROJECT_ID

Options

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

REST equivalent

GET /projects/<PROJECT_ID>

annif clear-project

Initialize the project to its original, untrained state.

annif clear-project [OPTIONS] PROJECT_ID

Options

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

REST equivalent

N/A

Subject index administration

annif train

Train a project on a collection of documents.

This will train the project using the documents from PATHS (directories or possibly gzipped TSV files) in a single batch operation. If --cached is set, preprocessed training data from the previous run is reused instead of documents input; see Reusing preprocessed training data.

annif train [OPTIONS] PROJECT_ID [PATHS]...

Options

-c, --cached, -C, --no-cached

Reuse preprocessed training data from previous run

-d, --docs-limit <docs_limit>

Maximum number of documents to use

-j, --jobs <jobs>

Number of parallel jobs (0 means choose automatically)

-b, --backend-param <backend_param>

Override backend parameter of the config file. Syntax: -b <backend>.<parameter>=<value>.

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

PATHS

Optional argument(s)

REST equivalent

N/A

annif learn

Further train an existing project on a collection of documents.

Similar to the train command. This will continue training an already trained project using the documents given by PATHS in a single batch operation. Not supported by all backends.

annif learn [OPTIONS] PROJECT_ID [PATHS]...

Options

-d, --docs-limit <docs_limit>

Maximum number of documents to use

-b, --backend-param <backend_param>

Override backend parameter of the config file. Syntax: -b <backend>.<parameter>=<value>.

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

PATHS

Optional argument(s)

REST equivalent

/projects/<PROJECT_ID>/learn

annif suggest

Suggest subjects for a single document from standard input.

This will read a text document from standard input and suggest subjects for it.

annif suggest [OPTIONS] PROJECT_ID

Options

-l, --limit <limit>

Maximum number of subjects

-t, --threshold <threshold>

Minimum score threshold

-b, --backend-param <backend_param>

Override backend parameter of the config file. Syntax: -b <backend>.<parameter>=<value>.

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

REST equivalent

POST /projects/<PROJECT_ID>/suggest

annif eval

Suggest subjects for documents and evaluate the results by comparing against a gold standard.

With this command the documents from PATHS (directories or possibly gzipped TSV files) will be assigned subject suggestions and then statistical measures are calculated that quantify how well the suggested subjects match the gold-standard subjects in the documents.

Normally the output is the list of the metrics calculated across documents. If --results-file <FILENAME> option is given, the metrics are calculated separately for each subject, and written to the given file.

annif eval [OPTIONS] PROJECT_ID [PATHS]...

Options

-l, --limit <limit>

Maximum number of subjects

-t, --threshold <threshold>

Minimum score threshold

-d, --docs-limit <docs_limit>

Maximum number of documents to use

-m, --metric <metric>

Metric to calculate (default: all)

-M, --metrics-file <metrics_file>

Specify file in order to write evaluation metrics in JSON format. File directory must exist, existing file will be overwritten.

-r, --results-file <results_file>

Specify file in order to write non-aggregated results per subject. File directory must exist, existing file will be overwritten.

-j, --jobs <jobs>

Number of parallel jobs (0 means all CPUs)

-b, --backend-param <backend_param>

Override backend parameter of the config file. Syntax: -b <backend>.<parameter>=<value>.

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

PATHS

Optional argument(s)

REST equivalent

N/A

annif optimize

Suggest subjects for documents, testing multiple limits and thresholds.

This command will use different limit (maximum number of subjects) and score threshold values when assigning subjects to each document given by PATHS and compare the results against the gold standard subjects in the documents. The output is a list of parameter combinations and their scores. From the output, you can determine the optimum limit and threshold parameters depending on which measure you want to target.

annif optimize [OPTIONS] PROJECT_ID [PATHS]...

Options

-d, --docs-limit <docs_limit>

Maximum number of documents to use

-b, --backend-param <backend_param>

Override backend parameter of the config file. Syntax: -b <backend>.<parameter>=<value>.

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

PATHS

Optional argument(s)

REST equivalent

N/A

annif index

Index a directory with documents, suggesting subjects for each document. Write the results in TSV files with the given suffix (.annif by default).

annif index [OPTIONS] PROJECT_ID DIRECTORY

Options

-s, --suffix <suffix>

File name suffix for result files

-f, --force, -F, --no-force

Force overwriting of existing result files

-l, --limit <limit>

Maximum number of subjects

-t, --threshold <threshold>

Minimum score threshold

-b, --backend-param <backend_param>

Override backend parameter of the config file. Syntax: -b <backend>.<parameter>=<value>.

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

DIRECTORY

Required argument

REST equivalent

N/A

annif hyperopt

Optimize the hyperparameters of a project using validation documents from PATHS. Not supported by all backends. Output is a list of trial results and a report of the best performing parameters.

annif hyperopt [OPTIONS] PROJECT_ID [PATHS]...

Options

-d, --docs-limit <docs_limit>

Maximum number of documents to use

-T, --trials <trials>

Number of trials

-j, --jobs <jobs>

Number of parallel runs (0 means all CPUs)

-m, --metric <metric>

Metric to optimize (default: NDCG)

-r, --results-file <results_file>

Specify file path to write trial results as CSV. File directory must exist, existing file will be overwritten.

-v, --verbosity <LVL>

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>

Set path to project configuration file or directory

Arguments

PROJECT_ID

Required argument

PATHS

Optional argument(s)

REST equivalent

N/A

annif run

Run a local development server.

This server is for development purposes only. It does not provide the stability, security, or performance of production WSGI servers.

The reloader and debugger are enabled by default with the ‘–debug’ option.

annif run [OPTIONS]

Options

-h, --host <host>

The interface to bind to.

-p, --port <port>

The port to bind to.

--cert <cert>

Specify a certificate file to use HTTPS.

--key <key>

The key file to use when specifying a certificate.

--reload, --no-reload

Enable or disable the reloader. By default the reloader is active if debug is enabled.

--debugger, --no-debugger

Enable or disable the debugger. By default the debugger is active if debug is enabled.

--with-threads, --without-threads

Enable or disable multithreading.

--extra-files <extra_files>

Extra files that trigger a reload on change. Multiple paths are separated by ‘:’.

--exclude-patterns <exclude_patterns>

Files matching these fnmatch patterns will not trigger a reload on change. Multiple patterns are separated by ‘:’.

REST equivalent

N/A