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