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​

activate​

Activate your VIKTOR account on the given environment, to get started developing.

viktor-cli activate <ENVIRONMENT> [flags]

Flags:
  -h, --help   help for activate

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
      --tag string       Used to identify the version of the app on the platform.
                         The tag may contain letters, numbers, dots and hyphens, max. 128 characters and should be unique.
      --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

clean-start​

Install and start your app in a clean development workspace.

viktor-cli clean-start [flags]

Flags:
      --app-dir string   Path to the directory that contains the app code (default: current working directory). (default ".")
  -h, --help             help for clean-start

clear​

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

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)
      --registered-name string   Registered name of the app (see 'viktor-cli apps') to connect to. When not defined, the 'registered_name' in the viktor.config.toml file be used.

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.

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', 'numpy', etc.)

The application should always be reinstalled when changes are made in the requirements.txt file.

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   (NOT recommended) 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-pip           Use this flag to enable installation using 'pip' instead of the default 'uv' as package manager
      --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. When not defined, the 'registered_name' in the viktor.config.toml file be used.
      --tag string               Used to identify the version of the app on the platform.
                                 The tag may contain letters, numbers, dots and hyphens, max. 128 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.
                                 When using GitHub Codespaces this setting will always be true.

quickstart​

Start developing from a sample app, or converted Excel file.

viktor-cli quickstart <SOURCE> <APP-NAME> [flags]

Flags:
  -h, --help   help for quickstart

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)
      --registered-name string                  Registered name of the app (see 'viktor-cli apps') to connect to. When not defined, the 'registered_name' in the viktor.config.toml file be used.
      --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