Command-line arguments | On‑Premise | Urbi Documentation
Maps
Search
Navigation
Urbi Pro
CityLens
Account
On‑Premise

Command-line arguments

The general example of running DGCLI is as follows:

docker run --rm \
    -v <path>:/dgctl-config.yaml \
    -v <path>:/dgctl-source \
    -v <path>:/dgctl-target \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    <mode> --config=/dgctl-config.yaml <arguments>

Where:

  • -v <path>:/dgctl-config.yaml - mounting the configuration file.

    As the inner path (file inside the container), you must always specify /dgctl-config.yaml.

  • -v <path>:/dgctl-source - mounting the directory for storing the installation artifacts.

    As the inner path (directory inside the container), you must always specify /dgctl-source. As the outer path (directory in the host machine), you must specify:

    • In license mode with the storage type fs - directory where you want to download the license.
    • In pull mode with the storage type fs - directory where you want to download the artifacts.
    • In restore mode - directory where the artifacts where previously downloaded using the pull mode.

    In other cases, this argument can be omitted.

  • -v <path>:/dgctl-target - mounting the directory for copying the installation artifacts.

    As the inner path (directory inside the container), you must always specify /dgctl-target.

    This argument is required only in restore mode when using file system as a storage.

  • -v /var/run/docker.sock:/var/run/docker.sock - passing the Docker socket into the Docker container.

    This argument is used together with the --apps-to-registry argument. If you are not going to use the Docker Registry, the arguments for connecting to the Docker socket can be omitted.

  • --user $(id -u):$(id -g) - launching DGCLI as a current system user.

  • <mode> - one of the modes supported by DGCLI:

    • license - downloads license from On-Promise servers to the S3 compatible storage or file storage on a private network. Requires internet access.
    • pull - downloads the up-to-date installation artifacts from the update servers. Requires internet access.
    • restore - restores installation artifacts stored in the file system. Does not require internet access.
    • save - saves downloaded installation artifacts from a source storage to the file system. Does not require internet access.
    • manifest - manages manifests in the S3 compatible storage. Does not require internet access.

  • --config=/dgctl-config.yaml - path where the configuration file is mounted in the Docker container (see mounting arguments above).

  • <arguments> - additional arguments:

    • --apps-to-registry - if this argument is specified, the Docker images will be placed into the Docker Registry and not into the storage.

      It is recommended to always use this argument, otherwise the Docker images will be placed into the storage with other artifacts. See more in the Architecture section.

      This argument is used together with -v /var/run/docker.sock:/var/run/docker.sock.

    • --workers - number of parallel worker threads which will download the data (defaults to 3, maximum is 8).

    • --attempt - number of attempts to restore the artifacts in case of write errors. Defaults to 3.

    • --overwrite - if this argument is specified, the existing files in the S3 compatible storage and in the Docker Registry will be overwritten.

    • --only-apps - download/restore the service images only, not the data.

    • --only-data - download/restore the service data only, not the images.

    • --only-license - download/restore the license file only.

    • --components=<component1,component2,...,component-n> (only in restore and save modes) - list of components for which to run the command. The list of components written in the configuration file is ignored.

    • --component=<component> (only in manifest mode) - component for which to run the command.

    • --services=<service-1,service-2,...,service-n> - download/restore artifacts for the specified services only. To run the command for a specific service, its parent component must be specified in the DGCLI configuration file. Supported services:

      • License service: license. The service belongs to the core component.
      • API Keys service: keys. The service belongs to the core component.
      • Map: mapgl-js-api, tiles-api-mobile-sdk, tiles-api-raster, tiles-api-vector, tilegen-api. The services belong to the api-platform component.
      • Search: catalog, search. The services belong to the api-platform component.
      • Navigation: navi. The service belongs to the api-platform component.
      • Urbi Pro: pro, pro-ui. The services belong to the pro component.
      • CityLens: citylens. The service belongs to the citylens component.
      • GIS Platform: gis-platform. The service belongs to the gis-platform component.
      • Platform Manager: platform. The service belongs to the api-platform component.

      You can use this argument together with --only-apps or --only-data to download only images or only data for the specified service.

    • --version (pull mode only) behaves differently depending on the DGCLI utility version:

      • For version 3.x: --version <component>:<version> - version of the On-Premise component to download (for example, --version=api-platform:1.0.0). The list of components and versions written in the configuration file is ignored. See the Releases section for available versions for each component.

        To specify multiple components, list them separated by commas or use the --version parameter multiple times.

        Note It is recommended to specify these values in the DGCLI configuration file instead of using the --version parameter. This approach is more convenient for debugging.

      • For version 2.x: --version <version> - version of the On-Premise software suite to download (for example, --version=1.43.0). Only for versions released before September 2025: see the On-Premise suite releases section.

    • --from-dir=/dgctl-source (restore mode only) - file system directory from which the installation artifacts should be restored.

      Always specify /dgctl-source as the directory path, accessible from inside the Docker container. The directory must be mounted using -v <path>:/dgctl-source.

      The directory must contain a manifest file (manifests/<component>/latest.json), which describes the folder structure for services. The simplest way to create the manifest and correct structure is to run DGCLI in pull mode with the file system as storage.

    • --dry-run - test launch: check if all required files for license request are present (license mode) or calculate the expected size of downloaded artifacts (pull mode).

    • --generate-values (pull mode only) - generate the general.yaml file with configuration parameters. To write the file to the local file system, mount the directory when running the utility using the -v <path>:/values argument. If the path is not specified, the file is deleted after running the utility.

    • --keep-count (manifest mode only) - the number of latest manifests to keep when cleaning up data. For details, see the Cleaning old data section.

    • --with-license-v1 - for license, save, and restore modes to work correctly for On-Premise versions 1.16.0 and lower.