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:

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

List apps that are connected to your VIKTOR development account.

viktor-cli apps [flags]

Flags:
-h, --help help for apps

check-system

Check if software environment is ready for developing VIKTOR apps. The following checks are performed:

default:

  • OS can access PyPI
  • OS can access VIKTOR domains
  • Python (64-bit) is installed and configured
  • VIKTOR credentials are valid

using --docker:

  • Docker is running
  • Docker can use correct container
  • Docker has access to user directory
  • Docker can access PyPI
  • Docker can access VIKTOR domains
  • VIKTOR credentials are valid
viktor-cli check-system [flags]

Flags:
--docker Run system checks for docker isolation mode
-h, --help help for check-system
--verbose Perform checks with more verbose logging to provide additional information

ci-install

Install the required dependencies inside a continuous integration environment.

viktor-cli ci-install [flags]

Flags:
-h, --help help for ci-install

ci-publish

Publish the app from a continuous integration environment. The following CI/CD platforms are supported:

  • Azure DevOps
  • GitHub Actions
  • GitLab CI/CD
viktor-cli ci-publish <NAME> [flags]

Flags:
-h, --help help for ci-publish
--use-filesystem Publish all files in current folder, as opposed to only files committed in git.

ci-test

Perform tests inside a continuous integration environment. The following command is executed: python -m unittest discover -s tests.

viktor-cli ci-test [flags]

Flags:
-h, --help help for ci-test

clear

Clear entities and entity types that are present in the database of your development environment.

viktor-cli clear [flags]

Flags:
-h, --help help for clear
--region us1 Specify the region in case of a multi-region organization if different than the default defined in the configuration file (e.g. us1)

configure delete-account

Delete a specific configuration account. This will not delete your account from the environment it is registered on!

viktor-cli configure delete-account [flags]

Flags:
-h, --help help for delete-account

configure list-accounts

Lists the configured accounts. These accounts are related to a specific VIKTOR development environment.

viktor-cli configure list-accounts [flags]

Flags:
-h, --help help for list-accounts

configure switch-account

Switch to another configuration account, without needing to reconfigure the current active account.

viktor-cli configure switch-account [flags]

Flags:
-h, --help help for switch-account

configure

Configure your development account, consisting of:

  • environment
  • email address
  • token
  • isolation mode
  • Python path

The following isolation modes can be selected:

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

A configuration file will be written to the '.viktor' folder in your user home directory.

  • Windows: this is the directory set in the USERPROFILE environment variable
  • Linux: this is the directory set in the HOME environment variable

The 'configure' command configures the account that is currently active. Use the --name flag to configure a specific account. A new configuration account is created if it does not yet exist.

viktor-cli configure [flags]

Flags:
-h, --help help for configure
--name string Configure a specific account

create-app

Create a new VIKTOR app with the given name within the current working directory using the latest SDK, as a starting point for development. If NAME is not provided, the app will be created directly inside the current working directory.

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

Flags:
--app-type string Type of app to be generated ['editor' | 'simple' | 'tree']. Mutually exclusive with --demo flag. (default "simple")
--demo Generate a demo app, including examples and comments.
-h, --help help for create-app

describe

Show latest published versions of an app by the given registered name. Shows the last 10 published app versions.

viktor-cli describe <NAME> [flags]

Flags:
-h, --help help for describe

fix

Fix deprecations by modifying the app source code. A diff is shown with the proposed changes and a prompt to accept or reject.

Multiple upgrades can be applied using the --upgrade flag: viktor-cli fix -u 41 -u 43 -u 45. All upgrades of the current SDK major version are applied when omitting the --upgrade flag.

viktor-cli fix [flags]

Flags:
--app-dir string Path to the directory that contains the app code (default: current working directory). (default ".")
-a, --apply directly apply fix
-h, --help help for fix
-k, --keep-original keep original files (e.g. foo.py -> foo.py & foo.orig.py)
-u, --upgrade 42 upgrade number (e.g. 42)

get-started

Get started developing with VIKTOR by activating your account on the given environment, and running the demo application.

viktor-cli get-started <ENVIRONMENT> [flags]

Flags:
-h, --help help for get-started

install

Install the app and its dependencies:

  • VIKTOR platform dependencies (e.g. viktor-connector)
  • app dependencies (e.g. VIKTOR SDK and others)

The application should always be reinstalled when changes are made in the requirements.txt file. Note that the installation is finished when the command-line returns. Sometimes there may be some waiting time between the command-line showing the message "Successfully installed..." and actually returning.

viktor-cli install [flags]

Flags:
--app-dir string Path to the directory that contains the app code (default: current working directory). (default ".")
--connector 5.2.0 Custom connector version (e.g. 5.2.0 (default "latest")
--dns 1.1.1.1 Custom DNS servers (e.g. 1.1.1.1) (default [])
-e, --env FOO=foo Additional environment variables (e.g. FOO=foo) (default [])
-h, --help help for install
--max-memory 500 (Docker only) Memory limit of the container in megabytes (e.g. 500) (default 500)
--use-truststore Use this flag to enable/disable installation of the app using the system truststore for HTTPS certificate verification instead of the bundled certifi certificates of pip (e.g. --use-truststore=false) (default true)

publish

Publish new versions of the application code to an app running in production. 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 commands.
viktor-cli publish --registered-name <NAME> [--use-filesystem] [flags]

Flags:
--app-dir string Path to the directory that contains the app code (default: current working directory). (default ".")
-h, --help help for publish
--registered-name string Registered name on the platform (see 'viktor-cli apps') to publish the app to.
--tag string Used to identify the version of the app on the platform.
The tag may contain letters, numbers, dots and hyphens, max. 20 characters and should be unique.
If the app directory is a git repository and its HEAD is on a tag it will default to this tag.
--use-filesystem Publish all files in current folder, as opposed to only files committed in git.

run

Run a given command in the container of the app. Use two dashes when using flags in your command, for example: viktor-cli run -- ls -a

viktor-cli run [flags]

Flags:
--app-dir string Path to the directory that contains the app code (default: current working directory). (default ".")
--dns 1.1.1.1 (Docker only) Custom DNS servers (e.g. 1.1.1.1) (default [])
--echo-command Only echo command, no execution
-e, --env FOO=foo Additional environment variables (e.g. FOO=foo) (default [])
-h, --help help for run
--max-memory 500 (Docker only) Memory limit of the container in megabytes (e.g. 500) (default 500)
--python 3.11 (Docker only) Python version used by the container (e.g. 3.11) (default "3.11")
--region us1 Specify the region in case of a multi-region organization if different than the default defined in the configuration file (e.g. us1)
-v, --volume {HOSTVOLUME}:{CONTAINERVOLUME} (Docker only) Additional volumes in container. Formatted as {HOSTVOLUME}:{CONTAINERVOLUME} (e.g. `/host/volume/path:/usr/src/docs`

start

Start the app, connect it to the platform and make it available in the browser for local development. The process can be stopped by pressing CTRL+C

viktor-cli start [flags]

Flags:
--app-dir string Path to the directory that contains the app code (default: current working directory). (default ".")
--autoreload Deprecated: autoreload is enabled by default and can be disabled with the '--no-autoreload' flag
--dns 1.1.1.1 (Docker only) Custom DNS servers (e.g. 1.1.1.1) (default [])
--echo-command Only echo command, no execution
-e, --env FOO=foo Additional environment variables (e.g. FOO=foo) (default [])
-h, --help help for start
--max-memory 500 (Docker only) Memory limit of the container in megabytes (e.g. 500) (default 500)
--no-autoreload Do not automatically reload code upon file changes
--region us1 Specify the region in case of a multi-region organization if different than the default defined in the configuration file (e.g. us1)
--silence-warnings Silence all (deprecation) warnings on the command-line
-v, --volume {HOSTVOLUME}:{CONTAINERVOLUME} (Docker only) Additional volumes in container. Formatted as {HOSTVOLUME}:{CONTAINERVOLUME} (e.g. `/host/volume/path:/usr/src/docs`)

test

Execute all unittests found inside the 'tests' directory, or in the 'path' provided. The following command is executed in case of a directory: python -m unittest discover -s tests, By providing the --path flag you can run specific tests (e.g. tests.test_filename.TestClass.test_function

viktor-cli test [flags]

Flags:
--app-dir string Path to the directory that contains the app code (default: current working directory). (default ".")
--dns 1.1.1.1 (Docker only) Custom DNS servers (e.g. 1.1.1.1) (default [])
--echo-command Only echo command, no execution
-h, --help help for test
--max-memory 500 (Docker only) Memory limit of the container in megabytes (e.g. 500) (default 500)
--path string Dotted path to the component (directory, module, class, or method) that should be tested, e.g. 'tests.test_model.TestModel'. (default: discover in 'tests'). (default "tests")
--region us1 Specify the region in case of a multi-region organization if different than the default defined in the configuration file (e.g. us1)

upgrade

Upgrade the CLI to the latest version.

viktor-cli upgrade [flags]

Flags:
-h, --help help for upgrade

version

Show the CLI version.

viktor-cli version [flags]

Flags:
-h, --help help for version