nacsos CLI

Last updated: 28/08/2026

A command-line interface (CLI) is a text-based way to interact with a platform or computer. Instead of clicking buttons in a graphical interface, you type commands into a terminal to perform tasks.

NACSOS has a CLI tool that you can run in your own computer. For large exports, or other resource heavy tasks, you can use your own computer's resources to finish the tasks faster. Additionally, it comes with addtional features that are not yet on the website version of NACSOS (e.g. support for importing more types of document formats).

Installing nacsos CLI

Prerequisites

You need:

• Python 3
• Access to the NACSOS Data GitLab repository

Installation

1. Clone the repository:

   git clone https://gitlab.pik-potsdam.de/mcc-apsis/nacsos/nacsos-data.git
   

   If you don't have git, you can also clone/download from the same URL.

2. Open the project directory:

   cd nacsos-data
   

3. Create a Python virtual environment:

   On macOS or Linux:

   python3 -m venv .venv
   source .venv/bin/activate
   

   On Windows PowerShell:

   python -m venv .venv
   .venv\Scripts\Activate.ps1
   

4. Upgrade pip:

   python -m pip install --upgrade pip
   

5. Install the CLI and its optional dependencies:

   python -m pip install -e ".[utils,scripts]"
   

   The utils and scripts extras install additional dependencies required by some CLI features.

6. Verify the installation:

   nacsos --help
   

   The command should display the available commands and options.

Troubleshooting

If the system cannot find the nacsos command, make sure that:

1. The virtual environment is activated.
2. You are using the same Python environment in which you installed the package.
3. The installation completed without errors.

If necessary, reinstall the package and its optional dependencies:

python -m pip install --force-reinstall -e ".[utils,scripts]"

Updating the CLI

To update an existing installation:

git pull
python -m pip install -e ".[utils,scripts]"

This updates the local installation and ensures that the optional dependencies remain available.

Additional access

For some commands available in the CLI tool, you will need addtional access, such as the connection details to the back-end database. Some commands may require a config file as an input. For such cases, you will need a configuration setup similar to the following:

config.env

NACSOS_DB__HOST="localhost"
NACSOS_DB__PORT=5432
NACSOS_DB__USER="nacsos"
NACSOS_DB__PASSWORD="secret"
NACSOS_DB__DATABASE="nacsos_core"

Using nacsos CLI

Run commands from the project directory while the virtual environment is activated:

For example:

nacsos --help

# Academic API wrappers (download and translate data)
nacsos apis --help
nacsos apis download --help
nacsos apis convert --help

# Helper for dealing with solr wildcards
nacsos apis solr-wildcards --help

# Importing data
nacsos import --help

# Exporting annotations
nacsos export --help

All available commands come with detailed descriptions in the --help flag. Unfortunately, there is no additional documentation about the functionalities of the CLI at the moment.