Command line interface

Once the engine module is installed as a dependency within another module, the ota command with the following subcommands is available.

In these commands:

<service_id> is the case sensitive name of the service declaration file without the extension. For example, for Twitter.json, the service ID is Twitter.
<terms_type> is the property name used under the terms property in the declaration to declare a terms. For example, in the getting started declaration, the terms type declared is Privacy Policy.

Tracking terms

ota track

Track the current terms of services according to provided declarations. The declarations, snapshots and versions paths are defined in the configuration. This command automatically runs a technical upgrade pass first to apply any engine, dependency, or declaration updates before tracking.

Example npx ota track

Note that the snapshots and versions will be recorded at the moment the command is executed, on top of the existing local history. If a shared history already exists and the goal is to add on top of it, that history has to be downloaded before executing that command.

ota track --help

Show help and available options for track command

Example npx ota track --help

ota track [--services <service_id>...]

Track terms of specific services only

Example npx ota track --services "Facebook" "LinkedIn"

ota track [--services <service_id>...] [--types <terms_type>...]

Track specific terms types of specific services only

Example npx ota track --services "Facebook" "LinkedIn" --types "Privacy Policy" "Terms of Service"

ota track --schedule [--services <service_id>...] [--types <terms_type>...]

Track terms on the schedule defined in the configuration

Example npx ota track --schedule

Applying technical upgrades

ota apply-technical-upgrades

Apply technical upgrades by generating new versions from the latest snapshots using updated declarations, engine logic, or dependencies, and by retrieving any missing snapshots for newly added source documents. Versions created during this process are labeled as technical upgrades to avoid false notifications.

Example npx ota apply-technical-upgrades

ota apply-technical-upgrades --help

Show help and available options for apply-technical-upgrades command

Example npx ota apply-technical-upgrades --help

ota apply-technical-upgrades [--services <service_id>...]

Apply technical upgrades to specific services only

Example npx ota apply-technical-upgrades --services "Facebook" "LinkedIn"

ota apply-technical-upgrades [--services <service_id>...] [--types <terms_type>...]

Apply technical upgrades to specific terms types of specific services only

Example npx ota apply-technical-upgrades --services "Facebook" "LinkedIn" --types "Privacy Policy" "Terms of Service"

Validating declarations

ota validate declarations [--services <service_id>...] [--types <terms_type>...]

Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services.

Example npx ota validate declarations --services "Facebook" --types "Privacy Policy"

ota validate declarations --schema-only [--services <service_id>...] [--types <terms_type>...]

Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible.

Example npx ota validate declarations --schema-only --services "Facebook" --types "Privacy Policy"

ota validate declarations --modified

Run ota validate only on files that have been modified in Git

Example npx ota validate declarations --modified

Linting declarations

ota lint [--services <service_id>...]

Test the format of declarations’ normalisation.

Example npx ota lint --services "Facebook" "LinkedIn"

ota lint --fix [--services <service_id>...]

Automatically correct formatting mistakes and ensure that all declarations are standardised

Example npx ota lint --fix

ota lint --modified

Run ota lint only on files that have been modified in Git

Example npx ota lint --modified

Validating metadata file

ota validate metadata

Check that the metadata file structure is valid

Example npx ota validate metadata

Publishing dataset

ota dataset [--file <filename>]

Export the versions dataset into a ZIP file, stored in the directory defined by dataset.storagePath in the configuration (./data/datasets by default) alongside a metadata.json file describing it. The file name defaults to the dataset title, defined in the configuration, followed by the current date. Only the latest dataset is kept: previous archives in that directory are deleted.

Example npx ota dataset --file dataset.zip

The latest dataset is exposed by the Collection API.

To also publish the dataset to configured platforms (GitHub releases, GitLab releases, and/or data.gouv.fr):

ota dataset --publish [--file <filename>]

Export and publish dataset to all configured platforms

Example npx ota dataset --publish

The dataset can be published to multiple platforms simultaneously:

GitHub releases: Requires OTA_ENGINE_GITHUB_TOKEN environment variable
GitLab releases: Requires OTA_ENGINE_GITLAB_TOKEN environment variable (used only if GitHub token is not configured)
data.gouv.fr: Requires OTA_ENGINE_DATAGOUV_API_KEY environment variable. To set up data.gouv.fr publishing, see the guide to publish datasets to data.gouv.fr.

These environment variables can be defined in a .env file.

Note: If both GitHub and GitLab tokens are configured, GitHub takes precedence. data.gouv.fr can be used alongside either GitHub or GitLab.

To export, and optionally publish, the dataset on the schedule defined by dataset.publishingSchedule in the configuration:

ota dataset --schedule [--publish] [--file <filename>]

Export, and optionally publish, the dataset on the schedule defined in the configuration

Example npx ota dataset --schedule --publish

Note: The --remove-local-copy option was removed in engine v16, as the local copy is now the reference dataset served by the Collection API. Remove it from the dataset:schedule script of the collection package.json, otherwise the command fails with an unknown option error.

Exposing the collection API

ota serve

Start the collection Web API server. The Web API will be available under <http://localhost>:<port>/<basePath>/<apiVersion>/<resource>. The server port and base path are defined in the configuration.

Example npx ota serve