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
-
Install the tool using pip.
pip install vortex-cli -
It is recommended to set the workspace you would like to work out of via the
VORTEX_HOMEenvironment variable.On Unix:
export VORTEX_HOME=/path/to/workspaceOtherwise, Vortex CLI will use a default 'vortex-cli-workspace' directory inside your home directory.
-
Run vortex with the
--initflag to create your workspace (If it doesn't already exist) and the necessary config files:vortex --init -
Define the servers you will be working with in the
servers.inifile inside the.configdirectory within your workspace. You can quickly access this using thecodecommand to view your workspace in VSCode.vortex codeIn the
servers.inifile, 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 username = myuser ; Optional - Prompted at runtime if not provided password = mypassword ; Optional - Prompted at runtime if not provided ; Optional gateway_path = vortex/gateway.pma ; the default: through the vortex gateway. Blank = webdesign's vortex API directly - see Backend: gateway or webdesign clone_with_resources = html,css,js ; resources with these extensions are always cloned - 'clone --get-resources' still clones ALL resources lib_path = ; optional extra jars to add to the classpath (the server's own jars are downloaded automatically - see 'vortex server libs') workspace_folders = ~/dev/shared,notes ; extra folders to mount in the generated .code-workspace files. Relative paths resolve against the workspace root. Under [DEFAULT] they are added to every workspace; here they apply to this server's workspace (and the global one) 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
Upgrading to 8.1
8.1 does two things. It replaces vortex config with plain top-level commands that read
servers.ini, which you edit by hand. And it stops a stale clone from silently overwriting
someone else's upload - another agent, in another workspace or on another machine - all
client side, with no gateway or webdesign change (see
Working alongside other agents). vortex config and the execute flags are removed: config is a stub
that runs nothing, prints the replacements and exits 1; the old execute flags are usage
errors (exit 2).
| 8.0 | 8.1 |
|---|---|
config --list-servers |
server list |
config --output-server-config |
server get [NAME] |
config --output-config-path |
the last line of server list |
config --output-workspace-path |
vortex --path |
config --update-vscode-settings / --reset-vscode-settings |
automatic on a servers.ini save, or code --refresh [--reset] |
config --set S O V |
edit servers.ini |
config --set-password |
keyring set vortex-cli:<server> <username> |
config --sample |
server get (every option it reads) |
execute --show-schedule / --refresh-agenda / --flush-cache |
execute schedule / refresh-agenda / flush-cache |
execute --refresh-design N |
execute refresh-design N or app refresh N |
execute --run PATH |
object run ID --app-id N |
status [--show-permissions] [--json] |
vortex [-s NAME] [--show-permissions] [--json] (no command) - plus the CLI version and the workspace |
vortex with no command (the workspace path) |
the live status of the default server: vortex-cli and workspace first, then the server (vortex --path prints just the path) |
use NAME |
server use NAME (use NAME still works) |
libs [--refresh] [-s NAME] |
server libs [NAME] [--refresh] |
| - | fetch - which cloned elements are out of step with the server, content and metadata (renames too); fetch --pull brings them in without losing local edits (3-way merges what it can) |
| - | object diff - server vs local (--mine: your edits, --theirs: the server's) |
compile --upload sends every class |
only those whose .java was edited since the clone synced it (--all: every one) |
find QUERY [--app-id ID] (clones only) |
object list [QUERY] [--app-id ID [--local]] [--json] - with --app-id it asks the server, so no clone is needed; QUERY is optional (every object) |
grep PATTERN |
object grep PATTERN [--json] - still the clones only |
db list --app-id ID (required) |
db list [--app-id ID] - without it, every application's connections; each row names its application (with --app-id, from its clone - the name is blank when it isn't cloned) |
- Server commands are one noun,
vortex server.vortex server listlists every server definition: host, backend, protected, the number of cloned apps, and*on the default.vortex server get [NAME](the default server without one) lists every option vortex reads with its value and where it comes from - the server's own section,[DEFAULT], the built-in default, or unset - plus where the credentials come from and any option vortex ignores (typos, renamed and removed options). Neither sends a request or prints a password. Both say whendefaultnames a server that isn't defined. executejoins its words, sovortex ex tell agenda schedule -s devneeds no quotes.- A protected server must be named. A command that writes to a server or sends a console
command (
execute,compile --upload, everyapp/object/keyword/dbwrite, and adb querythat is not aSELECT) refuses a protected server that was only picked up as thevortex usedefault (PROTECTED_DEFAULTin--json, nothing sent): pass-s NAME. Reads are unaffected. - Saving
servers.iniupdates the VS Code workspace files. A runningvortex watchrebuilds them on save (and says when a watched server's connection settings changed, which needs a restart); otherwise the nextvortexcommand does. Unchanged files are no longer rewritten, so VS Code doesn't reload for nothing. - Uploads are refused on a conflict.
watch,compile --uploadandobject update --source/--data(on a cloned app) compare the server's current row with the copy the clone last synced - before anything is sent. If someone else wrote it since, the upload is refused (CONFLICT, exit 1) and names who and when:vortex fetch ID --app-id N --pull, merge, upload again.--force(compile --upload,object update) overrides it, and needs a terminal (FORCE_NEEDS_TERMINALwithout one) so an agent can't. vortex findandvortex grepare stubs namingvortex object listandvortex object grep, and exit 1.vortex statusis a stub that namesvortex(the server's status, asstatuswas in 8.0) andvortex fetch(the clone against the server), and exits 1.vortex libsis a stub namingvortex server libs.- Manifests from before 8.1 still work. They lack the server's
updatedstamp, so the check compares content until the nextcloneorfetch --pullstores it. An olderwatchkept a failed upload's content as the clone's copy of the server, so an edit that never reached the server can look unedited:fetch --pullkeeps any file it replaces or removes under such a copy in<app>/.pull-backup/<time>/, andcompile --uploadsays when it skipped one. Runvortex fetch --app-id ID --pullonce per clone after upgrading (it also brings in metadata an older clone stored differently). - The upgrade is one-way. An 8.1 manifest stores a field 8.0 doesn't know, so an 8.0 CLI treats an 8.1 clone as unreadable - keep every machine and tool sharing a workspace on 8.1 (or reclone after going back).
fetch --pull --forceneeds a terminal, like the upload--force, and keeps every file it replaces or removes under<app>/.pull-backup/<time>/.
Upgrading to 8.0
8.0 reorganises the server commands into vortex <noun> <verb> over four entities - app,
object, keyword and db - so people and AI agents can drive a server predictably.
Everything else keeps its 7.x shape. It is a breaking release: each removed 7.x command still
exists for one release as a stub that runs nothing, prints its 8.0 replacement and exits 1.
| 7.x | 8.0 |
|---|---|
list |
app list (ls stays, = app list --local) |
new app |
app create |
new object / new object --update |
object create / object update |
new keyword, keyword APP --name --values |
keyword set NAME VALUE... --app-id APP |
keyword APP |
keyword list --app-id APP |
copy IDS --app-id DEST |
object copy IDS --app-id SRC --to-app-id DEST (--app-id now means the SOURCE) |
delete |
object delete IDS --app-id APP |
import / export |
app import (--group now required) / app export |
db ID --sql |
db query DB --app-id APP (no --update flag) |
db NAME --list / --schema T |
db list-tables / db get-table |
schema --add-table ... --delete-column |
db create-table ... db delete-column |
schema --ddl |
removed |
config --check-gateway |
status (vortex with no command since 8.1) |
- Numeric IDs, no guessing.
--app-idandAPP_IDare numeric everywhere (onlyclone APP...still takes a TemplateName, group orgroup/name), and--app-idis required on everyobject,keywordanddbcommand - it is never inferred from a clone. The server is-s/--server, else thevortex usedefault;SERVER:IDqualifiers and inferring the server from local clones are gone. - No clone needed for server work. When the app is cloned, every change is written into the clone too (see Local clones stay in sync).
- Output for scripts and agents. Readable by default;
--jsonon every entity command andfetchprints one envelope with a machine-readable error code. Exit codes are 0/1 (2 for bad arguments). See Output, errors and exit codes. gateway_pathalone picks the route. Set (the defaultvortex/gateway.pma) means the gateway, required - no probe, no fallback; blank means webdesign'svortexAPI directly. The 7.x server options for choosing SOAP and for pinning the log's database connection are gone and silently ignored if still present. Blankgateway_pathon any server that has no gateway (the old SOAP servers, and any server still running the old gateway) or 8.0 cannot reach it. SOAP is used only for console commands (status,execute) on servers without the gateway.protected = trueonly meanswatchskips the server unless--include-protected. The typed server-name confirmation is gone from every command; the gateway's roles are the protection.cloneno longer downloads the server libraries. It prints a one-linevortex libs --refreshhint when they are not cached;compilefetches them on first use.watchis no longer the only deploy path:object create/update --source/--dataandcompile --uploadupload content too. A running watch blocks them (and any compile).clean,grep,findtake one--app-id.list --show-inactiveandlist --connectionsare gone (the inventory has noDisableAppflag; usedb list --local).
Upgrading from 6.x or 7.x
6.0 added the gateway as an opt-in alternative to the SOAP designer, and 7.0 replaced the old
gateway application with today's pass-through to webdesign's vortex API (removing push,
pull, undo, render, agenda, compile and the undo journal). 8.0 supersedes both:
follow Upgrading to 8.0 - in particular, set gateway_path per server.
Upgrading to 5.0
5.0 changes some defaults you may rely on:
resource_ext_onlyis replaced byclone_with_resources- and the meaning flipped. Previously the extensions restricted what--get-resourcescloned. Now resources with the listed extensions are always cloned, and--get-resourcesclones every resource unfiltered. Rename the key inservers.ini(vortex warns while the old key is present).vortex watchnow watches every cloned app across all servers and uploads each change to the server it was cloned from. Use--serverfor the old single-server behaviour, and mark production definitionsprotected = trueso they are never watched by accident.find,grepandvortex list --localnow search all cloned apps unless--serveris given, and ID-taking commands infer their server from local clones (see below).
Usage
For a full list of commands see --help (every command and verb has its own:
vortex db update-column --help).
Command Overview
── app ──────────────────────────────────────────────────────────────────────
vortex app list [--group --name --template --strict --local --show-inherited
--all --ids-only --open-urls --open-dev-urls] [--json]
vortex app get APP_ID [--show-params] [--json]
vortex app create --name N --group G [--template --inherit-from --description]
vortex app update APP_ID [--name --group --description --inherit-from --template]
[--param NAME=VALUE ...] [--remove-param NAME ...]
vortex app export APP_ID... [--out-dir --exclude-source --timeout]
vortex app import FILE.pmx --name N --group G
vortex app refresh APP_ID (alias: refresh-design)
── object ───────────────────────────────────────────────────────────────────
vortex object get ID --app-id ID [--show-source --show-data] [--json]
vortex object create --app-id ID --type T --name N [--source FILE --data FILE
--content-type --comment --inherit-from --open-action
--save-action --parent-page] [schedule options]
vortex object update ID... --app-id ID [--source FILE --data FILE] [metadata options]
[schedule options]
schedule options (SCHEDULED_ACTION only): --schedule N|S|I|H|D|W|M|Y --interval N
--days SMTWHFA --start-time HH:mm --finish-time HH:mm --date N --month N
vortex object diff [ID...] --app-id ID [--mine|--theirs] [--stat --word-diff -U N] [--json]
[-- GIT-DIFF-OPTIONS... | --write DIR]
vortex object copy ID... --app-id SRC --to-app-id TGT [--copy-params]
vortex object list [QUERY] [--app-id ID [--local]] [--strict --inherits-from|--parent-page
--ids-only --show-params --type T...] [--json]
vortex object grep PATTERN [--app-id ID] [--output-paths|--output-apps]
[--include-resources|--type T...] [--json]
vortex object run ID --app-id ID
vortex object delete ID... --app-id ID [--yes]
── keyword ──────────────────────────────────────────────────────────────────
vortex keyword list --app-id ID [--local] [--reveal] [--json]
vortex keyword get NAME --app-id ID [--local] [--reveal] [--json]
vortex keyword set NAME [VALUE...] --app-id ID
vortex keyword delete NAME --app-id ID [--yes]
── db ───────────────────────────────────────────────────────────────────────
vortex db list [--app-id ID] [--local] [--json]
vortex db get DB --app-id ID [--json]
vortex db query DB --app-id ID [SQL | --file F | -] [--limit N] [--all-cols] [--json]
vortex db list-tables DB --app-id ID [--json]
vortex db get-table DB TABLE --app-id ID [--json]
vortex db create-table DB TABLE --app-id ID [--description]
vortex db update-table DB TABLE --app-id ID [--name --description]
vortex db delete-table DB TABLE --app-id ID [--yes]
vortex db create-column DB TABLE COLUMN --app-id ID --type T [--size N --pk --not-null
--unique --auto-increment --ref TABLE --cascade-delete --description]
vortex db update-column DB TABLE COLUMN --app-id ID [--name --type --size --description
--pk|--no-pk --null|--not-null --unique|--no-unique
--auto-increment|--no-auto-increment --ref TABLE|--no-ref
--cascade-delete|--no-cascade-delete]
vortex db delete-column DB TABLE COLUMN --app-id ID [--yes]
── Workspace ────────────────────────────────────────────────────────────────
vortex ls [app list filters] [--json] = app list --local
vortex clone APP... [--group --reclone --all --get-resources --open-urls --timeout]
vortex compile --app-id ID [--object ID...] [--upload [--include-source --all --force]]
[--show-warnings]
vortex fetch [ID...] [--app-id ID] [--all] [--pull [--force --no-merge]] [--json]
vortex watch [--include-protected]
vortex clean [--app-id ID] [--all --include-libs]
vortex code [--refresh [--reset]] [-s]
── Server and setup ─────────────────────────────────────────────────────────
vortex [-s NAME] [--show-permissions] [--json] (the server's live status)
vortex --path (the workspace path)
vortex log [-n --source -m --errors-only|--debug-only|--info-only -k -d] [--json]
vortex execute CMD... | flush-cache | refresh-agenda | refresh-design APP_ID | schedule
[--json] (alias: ex)
vortex server list [--json]
vortex server get [NAME] [--json]
vortex server use NAME (or: vortex use NAME)
vortex server libs [NAME] [--refresh] [--json]
vortex docs [--serve --port]
Every server command takes -s/--server NAME, after the command or before it (default: the
server set with vortex use;
a protected default must be named with -s to write or run a console command).
--show-X adds X to what is printed; --include-X adds X to what is sent.
Each entity command makes at most three small requests (three per ID for multi-ID
commands); only clone downloads a whole application.
Output, errors and exit codes
Output is readable by default - tables for list, key/value for get. --json (every
app, object, keyword and db command, fetch, server list|get|libs, execute, log,
ls and a bare vortex) prints
exactly one JSON envelope
on stdout; logs, progress and prompts always go to stderr. log --keep-alive --json never
ends, so it prints one envelope per line instead - one per log entry, as it arrives:
{"ok": true, "server": "dev", "data": {"appid": 9, "appname": "app", "appgroup": "bettrackr"}}
{"ok": false, "server": "dev", "error": {"code": "FORBIDDEN", "role": "GatewayDBWrite", "message": "..."}}
data keeps the server's own lowercase keys (designbucketid, appname). error.code is
the gateway's refusal code as sent (FORBIDDEN with the missing role, NOT_FOUND,
SYSTEM_DB, SQL_NOT_ALLOWED, WEBDESIGN_UNAVAILABLE, ...), or one the CLI sets:
NOT_FOUND (404), FORBIDDEN (a login page, 401/403), UNAVAILABLE (network, timeout, a
missing route), CONFIRMATION_REQUIRED, CONFLICT (an upload over someone else's newer
copy, or a pull that left something to merge), OUT_OF_SYNC (fetch: something needs a
pull), NOT_CLONED, FORCE_NEEDS_TERMINAL and ERROR. A hint says what to do next when
there is something to do.
Exit codes: 0 success, 1 failure (including a partly failed multi-ID command, whose
data then lists each ID's result), 2 bad arguments.
Nothing ever prompts without a terminal. The only wizards are app create and
object create run with no arguments in a terminal. Deletes look the item up, show it and
ask; --yes confirms, and without a terminal and without --yes they fail with
CONFIRMATION_REQUIRED and send nothing.
vortex --show-permissions lists every server command, whether this identity may run
it and the gateway role it is missing - read from the gateway's own route table (whoami),
so it is always the server's current rules.
Updates are partial
Pass only what changes. The CLI starts from the server's current values, because webdesign's writes replace whole rows (an omitted field is written blank):
app updatealways reads the application row first (GET ""), overlays the passed fields and writes it back.--param NAME=VALUEreplaces every param of that name,--remove-param NAMEremoves them; the whole param list is read, merged and written back.object updatealways reads the object from the server - never the clone, which lacksOptionsand unfetched resources and may hold undeployed edits - and writes it back with only the passed fields changed.--source FILE/--data FILEupload content (one ID).keyword setreplaces a keyword's whole value list - there is no per-value edit - and folds duplicate KEYWORD rows of the same name into the oldest.db update-table/update-columnstart from the current dictionary row; the--no-*forms and--nullturn things off.
Keyword and param writes are read-then-write: a concurrent edit between the two is lost.
No cache flush is needed after a write: webdesign's vortex API flushes the application's
cache itself (flushHttpServerCache) after every design, design-param, keyword, app-param
and application write, so a manual cache flush is never required after one.
Console shortcuts
vortex execute CMD... (or ex) sends any console command - the gateway's POST console,
which needs GatewaySystem, or the SOAP console without the gateway. The words are joined,
so no quoting is needed. These names are shortcuts that send the exact strings the server's
addins match:
| Shortcut | Sends | Effect |
|---|---|---|
schedule |
tell agenda schedule |
lists every scheduled action and its next run |
refresh-agenda |
tell agenda refresh |
AGENDA rereads every schedule now |
refresh-design APP_ID |
tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N |
rebuilds the application's design from its template, as app refresh does (a clone is then out of date) |
flush-cache |
tell http cache flush |
clears the design cache and all action class loaders |
tell http flush cache is not a valid command: the HTTP addin only matches
cache flush, and anything else does nothing, silently. Use flush-cache.
Two console operations act on one application or object, so they also live with those nouns:
| Command | Sends |
|---|---|
vortex app refresh APP_ID |
tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N - rebuilds the design from its template (a clone is then out of date) |
vortex object run ID --app-id N |
tell agenda run /group/app.pma/name - runs an ACTION or SCHEDULED_ACTION now |
The 8.0 flags (--show-schedule, --refresh-agenda, --flush-cache, --refresh-design,
--run) were removed in 8.1. app refresh was app refresh-design in 8.1.0; the old
name still works.
Local clones stay in sync
Server commands never need a clone. When the application is cloned, every write runs in this order:
- Take the application's workspace lock. A running
vortex watchholds it, so the command stops here - before any request - with a hint to stop the watch. - Make the change on the server.
- Write the server's reply into the clone.
If step 3 fails after the server change succeeded, the command exits 1, says what differs and
prints the command to re-sync (vortex clone APP_ID -s SERVER).
| Command | Local effect |
|---|---|
app update |
details and params; a name or group change moves the folder |
fetch --pull |
the objects' files (renamed with the server), zbin/ classes and manifest entries (local edits kept - see Working alongside other agents) |
object create / update / delete |
the object's file and manifest entry (a metadata-only change moves the file but never overwrites its content; an uploaded class also lands in zbin/) |
object copy |
the target application's clone |
keyword set / delete |
the clone's stored keywords |
compile |
writes zbin/; --upload stores the uploaded blobs |
app refresh / execute refresh-design |
none - prints that the clone is out of date |
app create / import / export, all db commands |
none |
A clone stores the design objects, the application's details (with its description), its
params, its keywords and its DB connections (id, name, database). keyword list --local and
db list --local read them with no request. Dictionary tables and columns are not stored.
Working alongside other agents
Several agents (or people) may edit one application from different sessions, workspaces or machines. The server has no locking, so the CLI protects uploads itself, from the clone's manifest: it holds the server's copy of every element as the clone last synced it - its base - and every upload compares three things first:
| Server now vs base | Upload |
|---|---|
| the same: nobody else wrote it | sent; the base becomes what was sent |
| already exactly what you are sending | sent (nothing is lost) |
| anything else | refused (CONFLICT, nothing sent), naming who changed it and when |
Both blobs count: a class uploaded on top of someone else's newer source is refused too.
vortex fetch --app-id 9 # before working: anything outdated?
vortex object diff --app-id 9 --theirs # what did the server get?
vortex fetch --app-id 9 --pull [ID...] # bring the clone up to date
...edit...
vortex compile --app-id 9 --object 396 --upload --include-source
vortex fetch lists the elements that are not in sync - edited (yours, ok to
upload), outdated (the server changed the content), metadata (the server renamed or
retyped it, or changed its comment, params, content type or inherit-from - the Server column
says what, e.g. renamed home -> landing), conflict (both changed), unresolved (a pull
conflict not merged yet), new / deleted on the server - and exits 1 when anything needs
a pull. It writes nothing. Without --app-id it checks the cloned application the current
directory is in, else every clone of the server. A whole application is one request as
heavy as a clone; IDs are one small request each.
vortex object diff shows the difference between two of the three versions: server ->
local by default (what an upload would change), --mine base -> local (your edits; no
request) or --theirs base -> server (what changed there). Without IDs it shows every
element that differs. With git installed it runs git diff --no-index on temporary files -
colour, --stat, --word-diff - otherwise Python's difflib. Everything after -- goes to
git diff as-is, after vortex's own options so it wins: options only, values attached
(-- --ignore-all-space --diff-algorithm=histogram -U10). --write DIR runs no diff and
writes the versions as files instead - DIR/base, DIR/local, DIR/server, each
<TYPE>/<file> - for any other tool (git diff --no-index DIR/base DIR/server,
git merge-file, an IDE).
vortex fetch --pull brings the server's changes in from the same request. Metadata is
always the server's: a rename moves your file - edits and all - to the new name, and the
comment, params and the rest are updated in the clone. Content: it takes the server's copy
wherever that loses nothing (outdated, new, deleted, missing locally) and keeps local edits
when the server is unchanged. When both
changed it runs git's 3-way merge (git merge-file on base, local and server - temporary
files, never a repository): edits that don't overlap are merged into your file, the
server's copy becomes the base, and the element is an ordinary edit to review and upload.
Overlapping edits - or binary content, no git, or --no-merge - keep your file, write the
server's copy to <app>/.conflicts/<TYPE>/<file> and make the server's copy the base. While that copy
exists the element is unresolved and every upload of it is refused: merge it into your
file, delete it, then upload. --force takes the server's copy over local edits; it only
ever changes the clone. A file already where a new element goes is never overwritten - it
becomes the element's local copy, with the server's under .conflicts/; a rename onto such
a file leaves the element where it is until the file is moved. --pull is
refused for an application while vortex watch runs on it.
compile --upload without --object sends only the classes whose .java was edited since
the clone synced it, so it can't re-send an untouched, older class over someone else's.
--force overrides a refusal and discards the server's newer copy; it needs a terminal.
The check is a read then a write, not atomic: two uploads of one element within milliseconds can still race. Keywords, app params and design params are not covered - each write replaces the whole set.
Scheduled actions
A scheduled action's schedule lives in its Options (a comma-separated name=value string
that the AGENDA addin reads - it is not a design param). object create and object update
set it with flags, for SCHEDULED_ACTION objects only:
vortex object create --app-id 62 --type scheduled_action --name Nightly --schedule N
vortex object update 7901 --app-id 62 --schedule D --start-time 02:30 --days MTWHF
vortex object update 7901 --app-id 62 --schedule N # stop it running
vortex object get 7901 --app-id 62 # the parsed schedule
| Flag | Option | Values |
|---|---|---|
--schedule |
Schedule= |
N never, S second, I minute, H hour, D day, W week, M month, Y year |
--interval |
Interval= |
units between runs, >= 1 |
--days |
Days= |
letters from SMTWHFA (S=Sun M=Mon T=Tue W=Wed H=Thu F=Fri A=Sat) |
--start-time |
StartTime= |
HH:mm, 24-hour; minute * = a random minute |
--finish-time |
FinishTime= |
HH:mm (up to 24:00); only used by S/I/H schedules |
--date |
Date= |
1-31 (M and Y) |
--month |
Month= |
1-12 (Y) |
- Merged, never replaced. Only the keys you pass change, in place and in canonical
casing;
LastRun(AGENDA's own) and any other key stay, in order. AGENDA reads the first case-insensitivekey=anywhere in the string, so a change an earlier entry would hide (StartDate=hidesDate=) is refused. - Checked first. Values are validated before anything is sent (exit 2). A schedule flag
on any other
--typeis a usage error; onobject update, every ID is read first and if any is not a scheduled action the whole command fails withWRONG_TYPEand nothing is written. - Applied at once. After a successful schedule change the CLI sends one
tell agenda refreshfor the whole command (the console routevortex executeuses: the gateway'sPOST console,GatewaySystem, or the SOAP console without the gateway). It has to: when an action starts, AGENDA writes back theOptionsit cached at its last refresh (AGENDAupdateDesignBucket/AgendaItem.getOptionString), so without a refresh a run within the next 15 minutes would undo the change. Only the moment between the write and the refresh remains. If the refresh fails or is refused, the change is still written and the command exits 0 with a loud warning to runvortex execute "tell agenda refresh" -s SERVER(naming the missing role forFORBIDDEN);--jsonreports"agendaRefreshed": true|false(plusagendaRefreshErrorwhen false). - LastRun race. AGENDA also writes
LastRunintoOptionswhenever the action starts; if that lands between the command's read and write, the oldLastRunis written back and the action may run one interval early.
Keyword values and secrets
Keywords are an application's live configuration, and in practice they hold credentials in
cleartext - API keys, passwords, vendor secrets, signing keys. vortex keyword therefore
redacts by default, in readable and --json output alike:
vortex keyword list --app-id 9 # every keyword (secrets redacted)
vortex keyword get AppVersion --app-id 9 # just this one
vortex keyword set AppVersion 3.7.0 --app-id 9 # replace its values
vortex keyword list --app-id 9 --reveal # print secret values in full
vortex keyword list --app-id 9 --local # the clone's copy, no request
- A keyword is treated as secret when its name contains a marker such as
password,passwd,passphrase,secret,credential,signature,apikey,privatekey,keystore,webhook,connectionstringormnemonic, or when any word of the name is one ofkey,keys,pwd,token,salt,hash,private,auth,bearer,cert,pem,jwt,dsn,otp,pin,seedorsig. Names are split on camelCase/snake_case/kebab-case, soAccessKeyIdandAPI_KEYare redacted whileMonkeyandConcertare not. The match is on the name only, and deliberately biased towards over-redaction: a false positive costs one--reveal. - Redacted values print as
<redacted>, one per value, so the value count stays visible. keyword setprints the prior values beside the new ones (redacted for secret names). Negative numbers such as-1work as values as they are. A value that looks like an option (-abc,--x) needs the options first and--before the name:vortex keyword set --app-id 9 -- Flags -abc --x.
Cloning a whole group
vortex clone is the one command that takes names as well as IDs:
vortex clone 13 # by ID
vortex clone bettrackr_app # by TemplateName
vortex clone bettrackr/app # by group/name
vortex clone BetTrackr # every non-inherited application in the BetTrackr group
vortex clone -a BetTrackr # ... including the inherited ones
vortex clone --group BetTrackr # explicitly a group, never a TemplateName
A group clone skips inherited applications unless --all/-a is given (the inventory has no
DisableApp flag, so disabled applications are not skipped). An application you name
outright is always cloned. Groups are matched the way app list --group matches them - a
case-insensitive substring - except that an exact group name always wins, so cloning
BetTrackr never drags in BetTrackrLegacy. If a partial name still spans several groups,
vortex stops and lists them. A bare word that is genuinely both a TemplateName and a group
is refused: use --group NAME or the ID. References may be qualified as SERVER:REF
(dev:BetTrackr).
Working with Multiple Servers
Each section in servers.ini defines a server (hosts must be unique across
sections). Cloned apps remember which server they came from:
vortex watchwatches every cloned app and uploads each change to the server it was cloned from. Use--serverto watch a single server only.object grep,lsandobject listwithout--app-idsearch across all cloned apps unless--serveris given.watch,cloneandcleantake a workspace-wide lock: only one watch at a time, and cloning or cleaning is refused while a watch is running. Commands that write into one cloned application (every mirrored server write,compile) take that application's lock, so they are refused for apps a watch is watching and run concurrently otherwise.- In VS Code, app folders are listed in per-server blocks with the server's jars
on the Java classpath. For a guaranteed-correct classpath, open a single
server's own workspace with
vortex code -s <server>.
Every server command targets -s <server>, else the vortex use default:
vortex server list # what is defined, and which is the default
vortex server get dev # every option of one server and where it comes from
vortex use dev # = vortex server use dev
vortex app list
Credentials
username/password can be left out of servers.ini (when set there, they win).
Each server's credentials otherwise resolve in this order and are only requested
when a command actually connects to that server - vortex server get NAME says which
one applies:
- The system keyring - store with
keyring set vortex-cli:<server> <username>(requirespip install keyring) - Per-server environment variables
VORTEX_USERNAME_<SERVER>/VORTEX_PASSWORD_<SERVER>(e.g.VORTEX_PASSWORD_DEV) VORTEX_USERNAME/VORTEX_PASSWORD- An interactive prompt naming the server
Protected Servers
protected = true means two things:
vortex watchskips the server unless--include-protectedis given, so saving a file can never hot-deploy to it by accident.- A write or console command never reaches it by default: when a protected server is only
the
vortex usedefault, those commands refuse to run until it is named with-s.
There are no write confirmations - the gateway's roles are the protection, so run agents against production with an identity whose roles fit the job.
Backend: gateway or webdesign
Each server picks where requests go, explicitly - nothing is probed and nothing falls back:
gateway_path |
Behaviour |
|---|---|
set (the default vortex/gateway.pma) |
through the vortex gateway: required and presumed installed; any failure is an error |
| blank | webdesign's vortex action directly (webdesign_path + /vortex): the same routes and bodies, with no role checks |
The gateway (vortex/gateway, a Puakma application you deploy) is system/webdesign's
vortex JSON API at a different address - https://<host>/vortex/gateway.pma/api/<path> is
webdesign's /system/webdesign.pma/vortex/<path> - with three things in front of it:
- Role checks. Every route needs a role, checked on the server:
GatewayDesignRead,GatewayDesignWrite,GatewayDBRead,GatewayDBWrite,GatewaySystemandAdmin(every route). Write implies read. A route the gateway does not map is refused.vortex --show-permissionsshows which commands your identity may run. - Guards. The gateway never addresses the Puakma system database (
SYSTEM_DB), never lets an id from one application be used under another (NOT_FOUND), and runs exactly oneSELECT/INSERT/UPDATE/DELETEper SQL request (SQL_NOT_ALLOWED: DDL,WITH, and any;). - Its own routes:
whoami(a barevortex), the server log (log), the console (execute),.pmxexport and import.
On a server with a blank gateway_path:
| Command | Behaviour |
|---|---|
app, object, keyword, db, clone, compile, watch, server libs |
the same routes, sent to webdesign's /vortex |
db query |
a CLI-side guard replaces the gateway's: one SELECT/INSERT/UPDATE/DELETE statement, refused otherwise with SQL_NOT_ALLOWED before anything is sent |
app export |
webdesign's ExportPMX |
vortex (no command) |
the console status command over SOAP (soap_path); --show-permissions says "no gateway: webdesign direct, no role checks" |
log |
a PMALOG query through webdesign's SQL route, on the system-database connection owned by the ungrouped puakma application (found once per run) |
execute |
the console command over SOAP |
app import |
unavailable (UNAVAILABLE) |
Without the gateway there are no role checks, no system-database block and no cross-app
ownership checks: use the gateway on any server an agent works against. If a gateway deploy
ever breaks the gateway, blanking gateway_path reaches the server through webdesign to fix
it.
There is no undo: nothing keeps a journal of what a write replaced. Deletes and uploads are final.
Note: the gateway's roles are only a real boundary for an identity whose sole route to the server is the gateway. Any identity that can reach
system/webdesignor deploy code can grant itself any role.
Java Design Objects, zbin/ and vortex compile
The server runs compiled classes, not source. There are three ways to get a class there:
vortex compile --app-id ID [--object ID...] --uploadbuilds the cloned application's Java intozbin/with ecj 3.46.0 (the compiler PuakmaVortexVSCode uses), run by the server'sjava_homeagainst the server's own jars, for the server'sjava_environment_name(JavaSE-17->--release 17; unset is an error naming the setting).--uploadsends each compiled class to its existing design element, one at a time (--include-sourceadds the.java): the--objectones, else those whose.javawas edited since the clone synced it (--all: every one). It refuses when anything failed to compile, refuses each element whose server copy changed since (see Working alongside other agents), and never creates elements (object createdoes). ecj is downloaded once from Maven Central; the server's libraries are fetched on first use.vortex object update ID --app-id APP --data Foo.class [--source Foo.java]uploads a class you built yourself.vortex watchuploads what the IDE's Java build writes intozbin/.
Tornado loads one class per design element, so nested classes never ship. compile treats
a source as a compile error - exit 1, its classes named, nothing written to zbin/ for
it, never uploaded - when it produces Outer$*.class files (inner, anonymous or local
classes). Use top-level SHARED_CODE classes instead. Lambdas and method references are
fine - they compile into the class itself (invokedynamic), no $ class. A switch
over an enum is fine: ecj keeps it inside the class (javac would add a synthetic Outer$1).
watch likewise refuses to upload a class compiled alongside $ siblings.
compile always writes into the clone, so it takes the application's lock and is refused
while vortex watch runs - with or without --upload.
Server-Provided Java Libraries
The IDE's Java build, IntelliSense and vortex compile need the Puakma framework jar and the
server's shared libraries on the classpath. vortex downloads them from each server's
webdesign vortex API (systemjar and libraries, through the gateway when
gateway_path is set - GatewayDesignRead) and caches them per server under
<workspace>/<host>/.lib/:
clonedoes not download them; it prints a one-linevortex server libs SERVER --refreshhint when they are not cached.compileandwatchfetch them on first use.vortex server libsshows what's cached for each server;vortex server libs --refreshre-downloads (name a server for just that one), e.g. after a server upgrade.- Each server's VS Code workspace (
vortex code -s <server>) uses that server's own cached jars, so identical class names on different servers/versions never cross-contaminate. vortex cleankeeps each host's.libcache; pass--include-libsto remove it as well.
Databases and the data dictionary
Every db command takes --app-id (every database route is app-scoped) and a DB: the
connection name, the database name or the connection ID, resolved within that application.
db list is the exception: without --app-id it lists every application's connections on
the server (one request per application), and every row names its application (id, group
and name). --local reads the clones instead - the --app-id one, else every clone of the
server.
vortex db list # every application on the server
vortex db list --app-id 9
vortex db query bettrackr --app-id 9 "SELECT * FROM account" --limit 5
vortex db query 3 --app-id 9 --file report.sql --json
vortex db get-table bettrackr invoice --app-id 9
db query sends the statement as given, apart from adding LIMIT n (default 10) to a
SELECT that has none - a full page of rows is flagged as possibly truncated. There is no
--update flag: the gateway classifies the statement (SELECT needs GatewayDBRead,
INSERT/UPDATE/DELETE GatewayDBWrite, everything else is refused). A numeric DB is one
request; a name is two.
The create-/update-/delete- table and column commands record design-time definitions in
the Puakma data dictionary (the PMATABLE/ATTRIBUTE tables). They never run DDL - deletes
only remove dictionary rows, never real tables or columns - so change the real table by hand.
vortex db create-table mydb invoice --app-id 9 --description "Customer invoices"
vortex db create-column mydb invoice invoice_id --app-id 9 --type INTEGER --pk --auto-increment
vortex db create-column mydb invoice total --app-id 9 --type NUMERIC --size 10,2 --not-null
vortex db create-column mydb invoice customer_id --app-id 9 --type INTEGER --ref customer
vortex db update-column mydb invoice total --app-id 9 --null
--type:VARCHAR,CHAR,LONGTEXT,INTEGER,DATETIME,NUMERIC,LONGBLOBorJSON.--sizeonly forVARCHAR(default 50),CHAR(default 1) andNUMERIC(default6,2); changing the type without--sizeresets the size to the new type's default.--ref TABLErecords the referenced table only - the dictionary has no referenced-column field. There is no--defaultor--position(webdesign ignores both).
Metadata
Release files for vortex-cli 8.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vortex_cli-8.1.1.tar.gz | 3.4 MB | Without provenance | Details for vortex_cli-8.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vortex_cli-8.1.1-py3-none-any.whl | Python 3 | none | any | Details for vortex_cli-8.1.1-py3-none-any.whl |
Total release size: 6.7 MB
Release files / vortex_cli-8.1.1.tar.gz
| Download URL | vortex_cli-8.1.1.tar.gz |
|---|---|
| Size | 3.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a7640b777730e5cccc27f2abae7907a96b4c3a6ccbd1071a2ce042aec94335e7
|
|
BLAKE2b-256 checksum How to use checksums |
6ee3c5eb29ff178884f613bd7005df96f4d39fc56155050a82bf5d4895d7fea5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / vortex_cli-8.1.1-py3-none-any.whl
| Download URL | vortex_cli-8.1.1-py3-none-any.whl |
|---|---|
| Size | 3.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4088da5cbecae4bef8a1424fa09fd8ddbbe9c242c2462fd78e6faa9b19b5f322
|
|
BLAKE2b-256 checksum How to use checksums |
0aa5e33953fd02f73d8f2269a7b034d03fc41741d94993f4fb94b27c069f2100
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Security for vortex-cli 8.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.