vortex-cli 4.21.0

Vortex CLI

Vortex CLI

Vortex CLI is a command line alternative to the Puakma Vortex IDE that simplifies the process of developing Puakma Applications on a Puakma Tornado Server using Visual Studio Code. It allows you to clone applications from the server to a local workspace, edit the files using Visual Studio Code, and automatically upload changes to the server as you work.

Vortex CLI also comes pre-packaged with the necessary Puakma .jar files for development.

Visual Studio Code and Extensions

While it is possible to use without it, this software has been purposefully designed for use with Visual Studio Code and the Project Manager For Java or the Extension Pack For Java extension. This software leverages Workspaces in Visual Studio Code and manages a vortex.code-workspace file within the workspace.

Installation

1. Install the tool using pip.

   pip install vortex-cli
   

2. It is recommended to set the workspace you would like to work out of via the VORTEX_HOME environment variable.

   On Unix:

   export VORTEX_HOME=/path/to/workspace
   

   Otherwise, Vortex CLI will use a default 'vortex-cli-workspace' directory inside your home directory.

3. Run vortex with the --init flag to create your workspace (If it doesn't already exist) and the necessary config files:

   vortex --init
   

4. Define the servers you will be working with in the servers.ini file inside the .config directory within your workspace. You can quickly access this using the code command to view your workspace in VSCode.

   vortex code
   

   In the servers.ini file, you can define as many servers as you need, each with their own unique name. For example:

   [DEFAULT] ; This section is optional and only useful if you have multiple definitions
   port = 80 ; Options provided under DEFAULT will be applied to all definitions if not provided
   soap_path = system/SOAPDesigner.pma
   default = server1 ; Useful when you have multiple definitions
   
   
   [server1] ; This can be called whatever you want and can be referenced using the '--server' flag
   host = example.com
   port = 8080 ; we can overwrite the DEFAULT value
   puakma_db_conn_id = 13
   username = myuser ; Optional - Prompted at runtime if not provided
   password = mypassword ; Optional - Prompted at runtime if not provided
   ; Optional
   lib_path = ; additional jars that should be included in the classpath
   java_home = /usr/lib/jvm/java-17-openjdk-amd64/ ; The local path to the JRE to use. Should be the same version running on your server
   java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
   

Usage

For a full list of commands see --help.

Command Overview

• code: Open the workspace in Visual Studio Code.
• use: Set the default server so you don't need to pass --server on every command. e.g. vortex use production
• list (or ls): List Puakma Applications on the server or cloned locally. (ls is an alias for vortex list --local)
• clone: Clone Puakma Applications and their design objects into the workspace or in the .pmx format.
• watch: Watch the workspace for changes to Design Objects and automatically upload them to the server.
• clean: Delete the locally cloned Puakma Application directories in the workspace.
• config: View and manage configuration.
• log: View the server log.
• find: Find Design Objects of cloned applications by name.
• grep: Search the contents of cloned Design Objects using a Regular Expression.
• new: Create new Design Objects, Applications, or Keywords. Use --update <ID> to update instead. Run without flags to launch an interactive wizard.
• copy: Copy a Design Object from one application to another.
• delete: Delete Design Objects by ID.
• db: Interact with Database Connections. Accepts --server/-s like other commands for one-off queries against another server.
• schema: Manage the Puakma data dictionary (PMATABLE/ATTRIBUTE): record table/column definitions and print the DDL to run by hand. Never executes DDL.
• compile (or build): Compile an application's Java Design Objects into zbin/ using javac.
• agent: Generate agent/editor support files (CLAUDE.md, Puakma skills, code snippets) in the workspace.
• docs: Open the Tornado Server Blackbook.
• execute: Execute a command on the server.

Switching Servers

If you work with multiple servers, use vortex use <server> to set the default instead of passing --server on every command:

vortex use production
vortex list
vortex watch

Interactive Wizards

Run vortex new object or vortex new app without any flags to launch a step-by-step wizard:

vortex new object
# → pick app from locally cloned list
# → pick design type
# → enter name
# → enter content type (resource/documentation only)
# → enter parent page, open action, save action (page only)
# → preview and confirm

vortex new app
# → enter name
# → pick from existing groups or enter a new one
# → enter description (optional)
# → preview and confirm

Skipping Confirmation Prompts

Pass --yes (or -y) to skip Y/y confirmation prompts, useful for scripting:

vortex --yes delete 123 456
vortex -y new object --name MyAction --app-id 10 --type action

Compiling Java Design Objects

vortex compile (alias build) compiles an application's Java Design Objects into zbin/ with a real javac, independent of the IDE's incremental build - real compile errors, a nonzero exit code on failure, and no stub class files. javac is found via java_home in the server config, then $JAVA_HOME, then PATH (--javac PATH to override), and --release is derived from the application's Java class version. It also warns when nested/inner/anonymous classes are produced, since these cannot be deployed as Design Objects.

vortex compile              # compile all locally cloned apps for the server
vortex compile 13           # compile one app
vortex compile 13 --upload  # also upload changed .class files

While vortex watch is running, --upload isn't needed - watch uploads new class files from zbin/ automatically.

Managing the Data Dictionary

vortex schema records design-time table and column definitions in the Puakma data dictionary (the PMATABLE/ATTRIBUTE tables, which also back vortex db --schema) and prints the matching DDL for you to run by hand. It never executes DDL, and deletes only remove dictionary rows - never real tables or columns.

vortex schema mydb --add-table invoice --description "Customer invoices"
vortex schema mydb --add-column invoice invoice_id --type BIGINT --pk --auto-increment
vortex schema mydb --add-column invoice total --type NUMERIC --size 10,2 --not-null
vortex schema mydb --add-column invoice customer_id --type BIGINT --ref customer.customer_id
vortex schema mydb --ddl invoice    # print CREATE TABLE from the dictionary

Agent Support Files

vortex agent copies bundled support files into the workspace .vscode directory so they are included in the generated code-workspace: a CLAUDE.md with Puakma ground rules for coding agents, a .claude/skills/ library covering Puakma development and the vortex workflow, and a vortex.code-snippets file with common Puakma Java/HTML snippets. Existing files are never overwritten, so they are safe to customise. These files are also generated automatically on vortex --init and before vortex code opens the workspace.