Skip to main content

Command-line interface (CLI)

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:

Download for Windows (no WSL2)Download for Linux (or WSL2)

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/CD 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

Configure your development account by specifying the environment, email address, and development account token. 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.

tip

When developing on multiple environments, you can make use of the --name flag to configure a specific account!

viktor-cli configure --name my-other-env

configure delete-account​

viktor-cli configure delete-account

Delete a specific configured development account.

caution

This will not delete your account from the environment it is registered on!

configure list-accounts​

viktor-cli configure list-accounts

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

configure switch-account​

viktor-cli configure switch-account

Switch to another configured development account.

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] [--app-type]
  • <NAME> is the name of the app for which a folder with equal name is created within the current working directory.
  • --demo 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.
  • --app-type can be used to generate an app based on the template of the specified type. Available app types are listed in the viktor.config.toml file. This cannot be used in combination with the --demo flag.

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​

caution

The first iteration of the publication feature has some limitations. Please see the publishing guide for more detail.

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, publishing will continue in the background. 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.

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] [--path]

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.

If you want to run specific tests instead of all tests in the tests directory, you can use --path to point to a function, class, or file.

For example:

viktor-cli test --path tests.test_filename.TestClass.test_function
viktor-cli test --path tests.test_filename.TestClass
viktor-cli test --path tests.test_filename

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.