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.

Annif supports tab-key completion in bash, zsh and fish shells for commands and options and project id, vocabulary id and path parameters. See README.md for instructions on how to enable the support.

Vocabulary administration

annif load-vocab

Load a vocabulary from a subject file.

Usage

annif load-vocab [OPTIONS] VOCAB_ID VOCAB_FILE

Options

-L, --language <language>: Language of TSV vocabulary 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

VOCAB_FILE: Required argument

REST equivalent

annif list-vocabs

List available vocabularies.

Usage

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

REST equivalent

GET /vocabs/

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.

Usage

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

REST equivalent

GET /projects/

annif show-project

Show information about a project.

Usage

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

Initialize the project to its original, untrained state.

Usage

annif clear [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

annif upload

Upload selected projects and their vocabularies to a Hugging Face Hub repository.

This command zips the project directories and vocabularies of the projects that match the given project_ids_pattern to archive files, and uploads the archives along with the project configurations to the specified Hugging Face Hub repository. An authentication token and commit message can be given with options. If the README.md does not exist in the repository it is created with default contents and metadata of the uploaded projects, if it exists, its metadata are updated as necessary.

Usage

annif upload [OPTIONS] PROJECT_IDS_PATTERN REPO_ID

Options

--token <token>: Authentication token, obtained from the Hugging Face Hub. Will default to the stored token.

--revision <revision>: An optional git revision to commit from. Defaults to the head of the “main” branch.

--commit-message <commit_message>: The summary / title / first line of the generated commit.

--modelcard, --no-modelcard: Update or create a Model Card with upload.

-v, --verbosity <LVL>: Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>: Set path to project configuration file or directory

Arguments

PROJECT_IDS_PATTERN: Required argument

REPO_ID: Required argument

REST equivalent

annif download

Download selected projects and their vocabularies from a Hugging Face Hub repository.

This command downloads the project and vocabulary archives and the configuration files of the projects that match the given project_ids_pattern from the specified Hugging Face Hub repository and unzips the archives to data/ directory and places the configuration files to projects.d/ directory. An authentication token and revision can be given with options. If the repository hasn’t been used for downloads previously (i.e., it doesn’t appear in the Hugging Face Hub cache on local system), the –trust-repo option needs to be used.

Usage

annif download [OPTIONS] PROJECT_IDS_PATTERN REPO_ID

Options

--token <token>: Authentication token, obtained from the Hugging Face Hub. Will default to the stored token.

--revision <revision>: An optional Git revision id which can be a branch name, a tag, or a commit hash.

-f, --force: Replace an existing project/vocabulary/config with the downloaded one

--trust-repo: Allow download from the repository even when it has no entries in the cache

-v, --verbosity <LVL>: Either CRITICAL, ERROR, WARNING, INFO or DEBUG

-p, --projects <projects>: Set path to project configuration file or directory

Arguments

PROJECT_IDS_PATTERN: Required argument

REPO_ID: Required argument

REST equivalent

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.

Usage

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

Options

-c, --cached, -C, --no-cached: Reuse preprocessed training data from previous run

-j, --jobs <jobs>: Number of parallel jobs (0 means choose automatically)

-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

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.

Usage

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

POST /projects/<PROJECT_ID>/learn

annif suggest

Suggest subjects for a single document from standard input (optionally with metadata) or for one or more document file(s) given its/their path(s).

This will read a text document from standard input and suggest subjects for it, or if given path(s) to file(s), suggest subjects for it/them.

Usage

annif suggest [OPTIONS] PROJECT_ID [PATHS]...

Options

-l, --limit <limit>: Maximum number of subjects

-t, --threshold <threshold>: Minimum score threshold

-L, --language <language>: Language of subject labels

-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>.

-D, --metadata <metadata>: Additional metadata for a document read from standard input. Syntax: -D <field>=<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

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.

Usage

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

Options

-l, --limit <limit>: Maximum number of subjects

-t, --threshold <threshold>: Minimum score threshold

-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)

-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

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.

Usage

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

Options

-j, --jobs <jobs>: Number of parallel jobs (0 means all CPUs)

-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

annif index

Index documents from directories or files, suggesting subjects for each document. Write the results in TSV files (for directories) or JSONL files (for files) with the given suffix (.jsonl suffix will be added to JSONL files).

Usage

annif index [OPTIONS] PROJECT_ID [PATHS]...

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

-L, --language <language>: Language of subject labels

-z, --gzip, -Z, --no-gzip: Gzip compress result files

-O, --output <output>: Redirect all output to the given file (or ‘-’ for stdout)

-i, --include-doc, -I, --no-include-doc: Include input documents in output

-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

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.

Usage

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

Options

-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 TSV. File directory must exist, existing file will be overwritten.

-d, --docs-limit <docs_limit>: Maximum number of documents to use

-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

annif run

Run Annif in server mode for development.

The server is for development purposes only.

Usage

annif run [OPTIONS]

Options

--host <host>

--port <port>

-v, --verbosity <LVL>: Either CRITICAL, ERROR, WARNING, INFO or DEBUG

REST equivalent

Other

annif detect-language

Detect the language of a single text document from standard input or for one or more document file(s) given its/their path(s).

Usage

annif detect-language [OPTIONS] LANGUAGES [PATHS]...

Arguments

LANGUAGES: Required argument

PATHS: Optional argument(s)

REST equivalent

POST /detect-language

annif completion

Generate the script for tab-key autocompletion for the given shell. To enable the completion support in your current bash terminal session run

To enable the completion support in all new sessions first add the completion script in your home directory:

Then make the script to be automatically sourced for new terminal sessions by adding the following to your ~/.bashrc file (or in some alternative startup file)

Usage

annif completion [OPTIONS]

Options

--bash

--zsh

--fish

REST equivalent