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.
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
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
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
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.
Currently the following CI/CD platforms are supported:
- Azure DevOps
- GitHub Actions
- GitLab CI/CD
ci-test
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 dependenciesdocker
: 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.
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.
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.
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
.
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 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:
- Prepare your code for release.
- Use the
publish
command. - 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.
- 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.
- If you want to check out the latest tag and status you can use the
apps
ordescribe
command.
run
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
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.