vortex-cli 8.0.1__tar.gz → 8.1.1__tar.gz

{vortex_cli-8.0.1 → vortex_cli-8.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 8.0.1
+Version: 8.1.1
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -100,12 +100,88 @@ While it is possible to use without it, this software has been purposefully desi
    ; 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 libs')
+   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](#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 list`** lists 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 when `default` names a server that
+  isn't defined.
+- **`execute` joins its words**, so `vortex ex tell agenda schedule -s dev` needs no quotes.
+- **A protected server must be named.** A command that writes to a server or sends a console
+  command (`execute`, `compile --upload`, every `app`/`object`/`keyword`/`db` write, and a
+  `db query` that is not a `SELECT`) refuses a protected server that was only picked up as
+  the `vortex use` default (`PROTECTED_DEFAULT` in `--json`, nothing sent): pass `-s NAME`.
+  Reads are unaffected.
+- **Saving `servers.ini` updates the VS Code workspace files.** A running `vortex watch`
+  rebuilds them on save (and says when a watched server's connection settings changed, which
+  needs a restart); otherwise the next `vortex` command does. Unchanged files are no longer
+  rewritten, so VS Code doesn't reload for nothing.
+- **Uploads are refused on a conflict.** `watch`, `compile --upload` and `object 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_TERMINAL` without one) so an agent can't.
+- **`vortex find` and `vortex grep` are stubs** naming `vortex object list` and `vortex object
+  grep`, and exit 1.
+- **`vortex status` is a stub** that names `vortex` (the server's status, as `status` was
+  in 8.0) and `vortex fetch` (the clone against the server), and exits 1. **`vortex libs`**
+  is a stub naming `vortex server libs`.
+- **Manifests from before 8.1 still work.** They lack the server's `updated` stamp, so the
+  check compares content until the next `clone` or `fetch --pull` stores it. An older
+  `watch` kept 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 --pull` keeps any file it replaces or
+  removes under such a copy in `<app>/.pull-backup/<time>/`, and `compile --upload` says
+  when it skipped one. Run `vortex fetch --app-id ID --pull` once 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 --force` needs 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`,
@@ -127,7 +203,7 @@ exists for one release as a stub that **runs nothing**, prints its 8.0 replaceme
 | `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` |
+| `config --check-gateway` | `status` (`vortex` with no command since 8.1) |
 
 - **Numeric IDs, no guessing.** `--app-id` and `APP_ID` are numeric everywhere (only
   `clone APP...` still takes a TemplateName, group or `group/name`), and `--app-id` is
@@ -137,7 +213,7 @@ exists for one release as a stub that **runs nothing**, prints its 8.0 replaceme
 - **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](#local-clones-stay-in-sync)).
 - **Output for scripts and agents.** Readable by default; `--json` on every entity command
-  and `status` prints one envelope with a machine-readable error code. Exit codes are 0/1
+  and `fetch` prints one envelope with a machine-readable error code. Exit codes are 0/1
   (2 for bad arguments). See [Output, errors and exit codes](#output-errors-and-exit-codes).
 - **`gateway_path` alone picks the route.** Set (the default `vortex/gateway.pma`) means the
   gateway, required - no probe, no fallback; blank means webdesign's `vortex` API directly.
@@ -195,6 +271,7 @@ vortex app update   APP_ID [--name --group --description --inherit-from --templa
                     [--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]
@@ -205,7 +282,14 @@ vortex object update ID... --app-id ID [--source FILE --data FILE] [metadata opt
                      [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 ──────────────────────────────────────────────────────────────────
@@ -215,7 +299,7 @@ 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 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]
@@ -232,31 +316,31 @@ vortex db update-column DB TABLE COLUMN --app-id ID [--name --type --size --desc
 vortex db delete-column DB TABLE COLUMN --app-id ID [--yes]
 
 ── Workspace ────────────────────────────────────────────────────────────────
-vortex ls        [app list filters]               = app list --local
+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]] [--show-warnings]
+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 grep      PATTERN [--app-id ID] [--output-paths|--output-apps]
-                 [--include-resources|--type]
-vortex find      QUERY [--app-id ID] [--strict --inherits-from|--parent-page --ids-only
-                 --show-params --type]
-vortex code
-vortex libs      [--refresh]
+vortex code      [--refresh [--reset]] [-s]
 
 ── Server and setup ─────────────────────────────────────────────────────────
-vortex status    [--show-permissions] [--json]
-vortex log       [-n --source -m --errors-only|--debug-only|--info-only -k -d]
-vortex execute   CMD | --refresh-design APP_ID | --run PATH | --show-schedule
-                 | --refresh-agenda | --flush-cache
-vortex config    --sample | --list-servers | --set S O V | --set-password
-                 | --output-config-path | --output-workspace-path | --output-server-config
-                 | --update-vscode-settings | --reset-vscode-settings
-vortex use       SERVER_NAME
+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` (default: the server set with `vortex use`).
+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
@@ -265,8 +349,11 @@ 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, and `status`) prints exactly one JSON envelope
-on stdout; logs, progress and prompts always go to stderr:
+`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:
 
 ```json
 {"ok": true, "server": "dev", "data": {"appid": 9, "appname": "app", "appgroup": "bettrackr"}}
@@ -277,7 +364,9 @@ on stdout; logs, progress and prompts always go to stderr:
 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` and `ERROR`. A `hint` says what to do next when
+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
@@ -288,7 +377,7 @@ Nothing ever prompts without a terminal. The only wizards are `app create` and
 ask; `--yes` confirms, and without a terminal and without `--yes` they fail with
 `CONFIRMATION_REQUIRED` and send nothing.
 
-`vortex status --show-permissions` lists every server command, whether this identity may run
+`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.
 
@@ -316,22 +405,31 @@ and application write, so a manual cache flush is never required after one.
 
 ### Console shortcuts
 
-`vortex execute CMD` sends any console command (the gateway's `POST console`, which needs
-`GatewaySystem`, or the SOAP console without the gateway). The shortcuts send the exact
-strings the server's addins match:
+`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 |
 |---|---|---|
-| `--show-schedule` | `tell agenda schedule` | lists every scheduled action and its next run (was `--schedule`) |
-| `--refresh-agenda` | `tell agenda refresh` | AGENDA rereads every schedule now |
-| `--flush-cache` | `tell http cache flush` | clears the design cache and all action class loaders |
-| `--refresh-design APP_ID` | `tell agenda run .../RefreshDesign?&AppID=N` | rebuilds the application's design from its template |
-| `--run PATH` | `tell agenda run /group/app.pma/action` | runs the action at that local path now |
+| `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`.
-`execute --schedule` was renamed to `--show-schedule` (`object update --schedule` now sets
-a schedule); the old flag runs nothing and prints the new one.
+`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
 
@@ -349,17 +447,86 @@ 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](#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 |
-| `execute --refresh-design` | none - prints that the clone is out of date |
+| `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
@@ -463,7 +630,8 @@ sections). Cloned apps remember which server they came from:
 
 - `vortex watch` watches **every** cloned app and uploads each change to the
   server it was cloned from. Use `--server` to watch a single server only.
-- `find`, `grep` and `ls` search across all cloned apps unless `--server` is given.
+- `object grep`, `ls` and `object list` without `--app-id` search across all cloned apps
+  unless `--server` is given.
 - `watch`, `clone` and `clean` take 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,
@@ -476,17 +644,20 @@ sections). Cloned apps remember which server they came from:
 Every server command targets `-s <server>`, else the `vortex use` default:
 
 ```
-vortex use dev
+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`. Each server's
-credentials resolve in this order and are only requested when a command
-actually connects to that server:
+`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:
 
-1. The system keyring - store with `vortex config --set-password -s <server>`
+1. The system keyring - store with `keyring set vortex-cli:<server> <username>`
    (requires `pip install keyring`)
 2. Per-server environment variables `VORTEX_USERNAME_<SERVER>` /
    `VORTEX_PASSWORD_<SERVER>` (e.g. `VORTEX_PASSWORD_DEV`)
@@ -495,10 +666,15 @@ actually connects to that server:
 
 #### Protected Servers
 
-`protected = true` means one thing: `vortex watch` skips the server unless
-`--include-protected` is given, so saving a file can never hot-deploy to it by
-accident. 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.
+`protected = true` means two things:
+
+- `vortex watch` skips the server unless `--include-protected` is 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 use` default, 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
 
@@ -516,22 +692,22 @@ webdesign's `/system/webdesign.pma/vortex/<path>` - with three things in front o
 - **Role checks.** Every route needs a role, checked on the server: `GatewayDesignRead`,
   `GatewayDesignWrite`, `GatewayDBRead`, `GatewayDBWrite`, `GatewaySystem` and `Admin`
   (every route). Write implies read. A route the gateway does not map is refused.
-  `vortex status --show-permissions` shows which commands your identity may run.
+  `vortex --show-permissions` shows 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 one
   `SELECT`/`INSERT`/`UPDATE`/`DELETE` per SQL request (`SQL_NOT_ALLOWED`: DDL, `WITH`, and
   any `;`).
-- **Its own routes:** `whoami` (`status`), the server log (`log`), the console (`execute`),
+- **Its own routes:** `whoami` (a bare `vortex`), the server log (`log`), the console (`execute`),
   `.pmx` export and import.
 
 On a server with a blank `gateway_path`:
 
 | Command | Behaviour |
 |---|---|
-| `app`, `object`, `keyword`, `db`, `clone`, `compile`, `watch`, `libs` | the same routes, sent to webdesign's `/vortex` |
+| `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` |
-| `status` | the console `status` command over SOAP (`soap_path`); `--show-permissions` says "no gateway: webdesign direct, no role checks" |
+| `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`) |
@@ -557,8 +733,11 @@ The server runs compiled classes, not source. There are three ways to get a clas
   server's `java_home` against the server's own jars, for the server's
   `java_environment_name` (`JavaSE-17` -> `--release 17`; unset is an error naming the
   setting). `--upload` sends each compiled class to its existing design element, one at a
-  time (`--include-source` adds the `.java`); it refuses when anything failed to compile and
-  never creates elements (`object create` does). ecj is downloaded once from Maven Central;
+  time (`--include-source` adds the `.java`): the `--object` ones, else those whose `.java`
+  was 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](#working-alongside-other-agents)), and never creates
+  elements (`object create` does). 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.
@@ -583,10 +762,10 @@ webdesign `vortex` API (`systemjar` and `libraries`, through the gateway when
 `gateway_path` is set - `GatewayDesignRead`) and caches them per server under
 `<workspace>/<host>/.lib/`:
 
-- `clone` does **not** download them; it prints a one-line `vortex libs --refresh -s SERVER`
+- `clone` does **not** download them; it prints a one-line `vortex server libs SERVER --refresh`
   hint when they are not cached. `compile` and `watch` fetch them on first use.
-- `vortex libs` shows what's cached for each server; `vortex libs --refresh` re-downloads
-  (add `-s <server>` for one server), e.g. after a server upgrade.
+- `vortex server libs` shows what's cached for each server; `vortex server libs --refresh`
+  re-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 clean` keeps each host's `.lib` cache; pass `--include-libs` to remove it as well.
@@ -595,8 +774,13 @@ webdesign `vortex` API (`systemjar` and `libraries`, through the gateway when
 
 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