Skip to main content

Command-line Interface

The VIKTOR command-line interface (CLI) is used to interact with your application code (installing dependencies, starting the app, running tests). This guide covers the installation and available commands.

Installation

Apps on the VIKTOR platform can be developed on Windows and Linux operating systems. Please consult the installation section for the differences between using the CLI with and without Docker, Hyper-V virtualization and WSL2.

note

If you are on Windows and want to use WSL2 you need to use the Linux version of the CLI.

Choose the CLI for your specific operating system and installation method below:

note

Mozilla Firefox currently has a bug that removes the file extension when downloading files. Please use a different browser to download the CLI.

A token is required to use the CLI. This token is linked to the email address associated with your development account. Configuration of the CLI can be done using the configure command. You will be asked to supply the email address and token during the configuration process. This action only needs to be performed once.

Commands

apps

viktor-cli apps

The command apps lists all applications that are connected to your developer account.

check-system

viktor-cli check-system [--verbose] [--docker]

The command check-system performs several checks to see if your computer is ready for developing VIKTOR apps.

If any of the system checks fails, additional information can be printed to the command-line by using the --verbose flag.

The --docker flag can be used if using VIKTOR with 'docker' isolation mode.

ci-install

caution

This is an advanced command and is not necessary during local development operations.

viktor-cli ci-install

Install the required dependencies inside a continuous integration environment.

ci-publish

caution

This is an advanced command and is not necessary during local development operations.

viktor-cli ci-publish <NAME>

<NAME> is the registered name on the platform (see 'viktor-cli apps').

Publish app from a continuous integration environment.

note

Currently the following CI-platforms are supported:

  • Azure DevOps
  • Github Actions
  • Gitlab CI/CD

ci-test

caution

This is an advanced command and is not necessary during local development operations.

viktor-cli ci-test

Perform tests inside a continuous integration environment.

clear

viktor-cli clear

When you are developing, you have your own database in which, among others, the entity types and entities are stored. If these are changed, the database structure is no longer compatible with your code. The clear command clears the database and enables a clean start.

This is applicable when:

  • you have changed entity type(s) and starting the app gives a ManifestError
  • you switch between apps, e.g. you first developed on app1 and now have to work on app2

configure

viktor-cli configure

Add your email address and development account token to the CLI's credentials file. If a credentials file already exists, the existing entries will be overwritten. Furthermore, the configure command can be used to select the isolation mode that you want to use for development on the VIKTOR platform:

  • venv: a Python virtual environment to manage dependencies
  • docker: code and dependency management using Docker containers

In case of venv isolation, you will also be prompted to provide the path to your Python installation.

configure list-accounts

viktor-cli configure list-accounts

Show the development account(s) the CLI has been configured with.

create-app

Create new VIKTOR app with given name within the current working directory using the latest SDK, as a starting point for development.

viktor-cli create-app <NAME> [--demo]

<NAME> is the name of the app for which a folder with equal name is created within the current working directory.

The --demo flag can be used to generate a demo app, including examples and comments. The demo app can be used as a starting point for beginner developers.

describe

If you want more information about the latest published version of a certain app, you can use the describe command. This command will list the 10 latest app versions. An app version is created with the publish command. The status of the app version is shown in the table.

viktor-cli describe <NAME>

<NAME> is the registered name on the platform (see 'viktor-cli apps').

fix

viktor-cli fix --upgrade ID [--apply] [--keep-original] [--app-dir]

Whenever you upgraded to the latest VIKTOR SDK version, deprecations may be introduced which require you to alter your code. In order to facilitate easy upgrading, we try to make an automated code modification available if possible. This fix command can then be used to automatically scan and refactor your code base if needed.

Multiple upgrades can be performed manually:

viktor-cli fix -u 41 -u 43 -u 45

Or all upgrades of the current SDK major version can be performed at once by omitting the --upgrade flag altogether (>= v13.2.0):

viktor-cli fix

To skip the user prompt, the flag --apply can be used, and the diffs are directly applied. In case you are not working in a git-like environment which preserves history, you could add the flag --keep-original to back up the original files.

caution

We cannot guarantee that all cases of a code conversion are covered by the provided fix. Please always check the diffs and applied changes to make sure your app keeps working correctly.

help

viktor-cli --help

This provides a list of all available commands. This flag can also be used on a specific command to obtain more information.

install

viktor-cli install [--app-dir]

This command installs all dependencies which are necessary to run the application:

  • viktor platform dependencies (e.g. connector)
  • app dependencies (requirements.txt)
    • SDK
    • (optional) extra dependencies

This is applicable when:

  • changes are made in requirements.txt (e.g. changing the viktor SDK version)

If the CLI is not called from within the app folder, a directory can be provided using the flag --app-dir.

note

The installation is finished when the command-line returns. Sometimes there is some time between the command-line showing the message "Successfully installed..." and actually returning. Wait until the command-line does so.

publish

The publish command can be used to push new versions of application code to an app running in production.

viktor-cli publish --registered-name <NAME> [--app-dir] [--tag]

<NAME> is the registered name on the platform (see 'viktor-cli apps') to publish the app to.

If the CLI is not called from within the app folder, a directory can be provided using the flag --app-dir.

A tag is used to identify the version of the app on the platform. By default, the command publishes on the platform on the same tag as the git tag associated with the app code. If the app folder is not a git repository, the current branch of the repository (HEAD) does not represent a (valid) tag, the repository tag is already occupied on the platform, or you want to explicitly set the tag for any other reason, a tag can be provided using the flag --tag. The tag should be unique, may only contain letters, numbers, dots and hyphens and has a maximum length of 20 characters.

If you are ready to publish your app, please use the following flow:

  1. Prepare your code for release.
  2. Use the publish command.
  3. Once you press enter you will see a spinner which you can use to monitor the publication. At this moment it not possible to cancel the process once you see the spinner. It is not a problem if you accidentally close the CLI at this point. The publishing of the app will continue on the system. During publication several checks will be performed. If any problems occur you will be presented with the reason for failure.
  4. There might be a small delay between the 'publication successful' message from the CLI and the actual update of the app. If this is the case, just refresh your browser.
  5. If you want to check out the latest tag and status you can use the apps or describe command.
note
  • Although we use the term <TAG> as a variable for the publish command, this is not linked to the git tag. The CLI will not check out the tag you specify in the publish command, you will have to do this manually first (e.g. git checkout <TAG>).
  • If you are using git the CLI respects the .gitignore file.
  • If you have any uncommitted changes or unstaged files, the publish command will fail as a safety mechanism.
caution

The first iteration of the publication feature has some limitations. These limitations are described below. If you want to publish an app and encounter one of these limitations, please reach out to your contact person at VIKTOR to publish the application.

  • In order to publish an app, the environment should be created first.

  • It is not possible to clear the database of an app before publishing.

  • It is not possible to set / update the VIKTOR_APP_SECRET with the publish command.

  • It is not possible to publish an app that has incompatible entity type changes, e.g:

    • Removal / renaming of entity types that are already present in the database
    • Changing names of top-level entities

In case of an entity type incompatible publish, follow these steps:

  1. Use the publish command with the new app code
  2. Wait for it to fail due to the incompatible change
  3. Notify your contact person at VIKTOR and mention the incompatible change(s)
  4. Await VIKTOR to republish with necessary adjustments in the database

run

caution

This is an advanced command and is not necessary during normal development operations.

viktor-cli run COMMAND [--app-dir]

This command provides an entry point for the container, when using Docker. When using a virtual environment as isolation mode, the CLI will execute the supplied command with the virtual environment activated. An example application is running the unit tests:

viktor-cli run -- python app/script.py

The double dashes are present to distinguish between command-line flags which belong to the CLI and command-line flags which belong to the (Docker) command.

If the CLI is not called from within the app folder, a directory can be provided using the flag --app-dir.

start

viktor-cli start [--app-dir]

This command connects the application code with the platform.

If the CLI is not called from within the app folder, a directory can be provided using the flag --app-dir.

When a file change is detected, the code is automatically reloaded. If you don't want this, add the flag --no-autoreload.

Stopping the process: Control + C

note

VIKTOR applications are published with 500 MB of RAM by default. If this is not sufficient the flag --max-memory can be used to change the RAM of the container in development. If the memory limit has been changed, this limit should also be modified when publishing your application to production.

test

viktor-cli test [--app-dir]

This command runs all tests inside the app's tests directory using the built-in unittest package.

If the CLI is not called from within the app folder, a directory can be provided using the flag --app-dir.

upgrade

viktor-cli upgrade

Upgrade the CLI to the latest version. If you have an old version, a warning message will appear when you execute a command.

version

viktor-cli version

Show the version of the CLI.