exist-shell 0.1.1__tar.gz → 0.2.0__tar.gz

{exist_shell-0.1.1 → exist_shell-0.2.0}/.github/workflows/docs.yml

@@ -16,10 +16,10 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.13"
 

{exist_shell-0.1.1 → exist_shell-0.2.0}/.github/workflows/e2e.yml

@@ -14,7 +14,7 @@ jobs:
     outputs:
       flags: ${{ steps.list.outputs.flags }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Build image matrix from --list-images
         id: list
         run: |
@@ -31,9 +31,9 @@ jobs:
         flag: ${{ fromJson(needs.matrix.outputs.flags) }}
       fail-fast: false
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - run: sudo apt-get install -y libxml2-utils
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - run: uv sync
@@ -88,7 +88,7 @@ jobs:
             done
           } > comment.md
           cat comment.md
-      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+      - uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v2
         with:
           header: e2e
           path: comment.md

{exist_shell-0.1.1 → exist_shell-0.2.0}/.github/workflows/release.yml

@@ -15,7 +15,7 @@ jobs:
     if: github.actor == 'ambs'
     environment: release
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Verify signed tag
         run: |
@@ -24,7 +24,7 @@ jobs:
         env:
           GPG_PUBLIC_KEY: ${{ secrets.GPG_PUBLIC_KEY }}
 
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
 

{exist_shell-0.1.1 → exist_shell-0.2.0}/.github/workflows/ruff.yml

@@ -12,8 +12,8 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - run: uv sync
@@ -37,7 +37,7 @@ jobs:
               echo '```'
             } > comment.md
           fi
-      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+      - uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v2
         if: github.event_name == 'pull_request'
         with:
           header: ruff

{exist_shell-0.1.1 → exist_shell-0.2.0}/.github/workflows/tests.yml

@@ -12,8 +12,8 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - run: uv sync
@@ -34,7 +34,7 @@ jobs:
             echo "**${test_line}**  "
             echo "**Coverage: ${coverage}**"
           } > comment.md
-      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+      - uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v2
         if: github.event_name == 'pull_request'
         with:
           header: tests

{exist_shell-0.1.1 → exist_shell-0.2.0}/.github/workflows/ty.yml

@@ -12,15 +12,15 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - run: uv sync
       - name: Run ty
         id: ty
         continue-on-error: true
-        run: uv run ty check src/ 2>&1 | tee ty.log
+        run: uv run ty check src/ tests/ 2>&1 | tee ty.log
       - name: Build PR comment
         if: github.event_name == 'pull_request'
         run: |
@@ -37,7 +37,7 @@ jobs:
               echo '```'
             } > comment.md
           fi
-      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+      - uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v2
         if: github.event_name == 'pull_request'
         with:
           header: ty

{exist_shell-0.1.1 → exist_shell-0.2.0}/.gitignore

@@ -8,3 +8,5 @@ dist/
 .ty/
 .coverage
 coverage.xml
+plans/
+CLAUDE.local.md

exist_shell-0.2.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## 0.2.0 - 2026-07-28
+
+### Fixes
+
+- `config.toml` (which stores server passwords in plaintext) was written with default umask permissions — typically world-readable on multi-user machines. It is now written `0600` with the config directory at `0700`, and `exsh` warns on stderr when an existing config file is group/world-readable
+- Non-401/404 HTTP errors (most notably `403 Forbidden`) leaked a raw `httpx` traceback; they now exit cleanly with a one-line error message. `cp` local→remote also gained the XML well-formedness check that `put` and `sync` already had
+- The sync manifest was keyed only by the remote path, so syncing the same remote collection against two different local directories shared one manifest and silently corrupted each other's per-file state (false conflicts, wrong skip decisions). The manifest key now includes the resolved local directory; existing manifests are re-keyed via a one-time full recheck on the next sync
+- A single failed transfer during sync left the rest of the queue finishing silently in the background with no progress output, ending in a generic unattributed error. Failures are now reported per file (`! <path>  (error: ...)`) as they happen, the remaining queue keeps draining, the summary shows a `failed` count, and sync exits non-zero when anything failed
+- `is_remote()` classified any argument containing `:` as a `nick:path` remote target, so Windows paths (`C:\data\doc.xml`) and any local path with a colon in a directory component were always misparsed as a remote nick. A prefix is now only treated as a nick when it matches a configured collection, isn't a single-letter drive prefix (`C:\`, `C:/`), and doesn't itself contain a path separator. Server/collection nicks must now be at least 2 characters, guaranteeing a configured nick can never collide with a Windows drive letter
+- `mv` of a collection onto itself (`exsh mv nick:/a nick:/a`) or into itself via a trailing slash (`exsh mv nick:/a nick:/a/`) copied the contents onto/into the source and then recursively deleted it, destroying the data. `mv` now aborts with an error when the target is the same as, or nested inside, the source, for both collections and single documents
+- `cat`/`cp`/`mv`/`edit`/`sync` downloading an executable resource (`.xql`, `.xqm`) ran the query on the server and returned its result instead of the document's raw source
+- The above fix relied on eXist's `_source=yes` REST parameter, which requires the path to be explicitly allowlisted in the server's `descriptor.xml` — not the default for anything under `/db`, regardless of the caller's own read permission. This returned `403 Forbidden` for every executable-resource download (`.xq`, `.xql`, `.xqm`, `.xquery`, `.xqy`, `.xqws`) on an unconfigured (i.e. most) server. These resources are now fetched via `util:binary-doc()`, which only needs the read + query-eval permission already required to execute them
+- `rm <nick>:<path>` on a path that is a collection silently deleted the entire subtree with no confirmation, since eXist's `DELETE` is recursive on collections. `rm` now refuses a collection target unless `--recursive`/`-r` is given, and prompts for confirmation unless `--yes`/`-y` is also passed
+- `create_collection`, `is_collection`, and `move_document` embedded paths/names into generated XQuery without escaping `"`/`&`, unlike every other client method — a path or name containing either broke the query (or, in `move_document`, changed its meaning)
+- `rm` and `find --remove` never invalidated the completion cache after deleting, so deleted documents kept appearing in tab completion until the cache TTL expired
+
+### Enhancements
+
+- **Independent client timeouts**: connect (10s), read (30s), and write (10s) now have separate budgets instead of one flat 30s timeout for every phase, and timeout errors say which phase failed — "Cannot connect to ..." for handshake failures vs "Server at ... did not respond in time" for read/write timeouts.
+- **Faster, correct bash tab-completion for `nick:path` targets**: the generated bash completion script now handles the `:` word-break correctly (no more `dlp:dlp:...` insertions), completing a collection no longer needs an extra backspace before continuing into it, and completion listings are filtered and capped server-side and cached per prefix so progressive typing reuses a single fetch. Re-run `exsh --install-completion bash` after upgrading to pick up the new script.
+- **Exit code 130 on Ctrl+C** for the whole CLI (previously sync-only), including during shell completion itself, which Typer/click don't handle on their own.
+- **Parallel sync (`--jobs N`)**: uploads, downloads, and remote directory listings now run concurrently. The `--jobs N` flag (default: 4) controls the number of parallel workers. Use `--jobs 1` to restore fully sequential behaviour.
+- **Clean Ctrl+C handling**: interrupting a sync now exits with code 130, saves the manifest (so the next run can resume), and prints a single `Interrupted.` message instead of a Python traceback.
+- **`exsh find`**: locate documents by XPath expression anywhere in their content (`exsh find <nick>[:<path>] --query 'foo[@type="draft"]'`), with `--remove`/`--yes` to delete every match in one step.
+- **`exsh exec --resource <nick>:<path.xql>`**: execute a stored `.xql`/`.xqm` resource in place (a plain `GET`, matching how eXist runs these resources natively) instead of downloading it and re-running it locally. Repeat `-p/--param NAME=VALUE` to forward query-string parameters as external variables.
+- **`exsh sync --exclude`**: repeatable glob patterns to skip paths on both sides of a sync (`--exclude '*.tmp' --exclude build`). A pattern with `/` matches that relative path and its subtree; one without `/` matches any path segment at any depth. Patterns persist in the sync manifest per (server, remote path, local folder), so later runs keep excluding without the flag; new patterns merge into the stored list and `--clear-exclude` resets it. Excluded paths are never transferred and never deleted by `--delete`. Files synced before becoming excluded are deleted on both sides after confirmation (`--yes` skips the prompt, declining keeps the files, `--keep-excluded` keeps them without asking); either way they stop being tracked.
+
+## 0.1.2 - 2026-06-23
+
+### Documentation
+
+- Document installing `exsh` from PyPI (`uv tool install`, `pipx install`, `uvx --from`); the existing `git+https://...` instructions are kept as an alternative for tracking unreleased commits
+
+## 0.1.1 - 2026-06-23
+
+### Fixes
+
+- Complete PyPI project metadata: `readme`, `license` (MIT), `authors`, `classifiers`, `project.urls`, and `keywords` were all missing, leaving the 0.1.0 PyPI listing with no description, license, or links
+- Add `LICENSE` file (MIT)
+
+## 0.1.0 - 2026-06-23
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `server add / ls / rm` | Register, list, and remove eXist-db server configurations; `rm` cascade-removes associated collections |
+| `server rename <old> <new>` | Rename a server nick; all registered collections are updated automatically |
+| `collection add / new / ls / rm` | Manage named collection shortcuts; `new` creates the collection on the server and registers it in one step (idempotent: no-op if already exists) |
+| `ls [path]` | List documents and sub-collections at a remote path; `--sort name\|time`, `--reverse`, `--names-only` |
+| `cat <path>` | Print a remote document to stdout; `--raw` skips binary detection |
+| `put <path>` | Upload a document from stdin or a local file; auto-detects MIME type |
+| `cp <src> <dst>` | Copy documents local↔remote or remote↔remote |
+| `rm <path...>` | Delete one or more remote documents |
+| `mkdir <path>` | Create a remote collection (idempotent) |
+| `edit <path>` | Download, open in `$VISUAL`/`$EDITOR`, re-upload if changed |
+| `sync push/pull <dir> <path>` | Sync a local directory tree with a remote collection; supports `--delete`, `--dry-run`, `--force` |
+| `mv <src> <dst>` | Move or rename a document or collection; trailing `/` on dest moves into that collection; cross-server moves not supported |
+| `exec <nick>[:<path>]` | Read an XQuery script from a file or stdin, optionally preprocess it (version declaration, functx import), validate locally with BaseX or Saxon (auto-detected via PATH), then execute against eXist and print the result; supports `--no-fix`, `--no-validate`, `--validator`, `--list-validators` |
+| `user ls` | List user accounts and their groups; accepts `@server` positional |
+| `user add <user[@server]>` | Create a user account (prompts for password) |
+| `user rm <user[@server]>` | Remove a user account |
+| `user info <user[@server]>` | Show user account details |
+| `user passwd <user[@server]>` | Change a user's password; `--stdin` for scripting |
+| `group ls` | List groups and their members; accepts `@server` positional |
+| `group add <group[@server]>` | Create a group |
+| `group rm <group[@server]>` | Remove a group |
+| `chown <spec> <path>` | Change owner and/or group of a document or collection; `--recursive / -R` for collections; spec forms: `owner`, `:group`, `owner:group` |
+| `chmod <mode> <path>` | Change POSIX permissions of a document or collection; `--recursive / -R` for collections; accepts octal (`0755`) or symbolic (`u+x`, `go-w`, `a=rw`) modes |
+
+### Infrastructure
+
+- Shell completion for collection/document paths (with TTL cache)
+- `<name>@<server>` syntax for ad-hoc server targeting in `collection add`, `collection new`, `user *`, and `group *`
+- `--server` option on all commands completes registered server nicks
+- Shell completion for `<name>@<server>` and `@<server>` argument forms
+- Path traversal validation and URL encoding
+- Google-style docstrings enforced via ruff
+- CI: pytest + coverage (Codecov), ruff, ty, e2e test suite against live eXist-db in Docker
+- CI: sticky PR comments for tests (counts + coverage), ruff, ty, and e2e workflows
+- CI: e2e workflow with dynamic image matrix from `--list-images`; `fail-fast: false`

{exist_shell-0.1.1 → exist_shell-0.2.0}/Makefile

@@ -9,7 +9,7 @@ test: ## Run tests
 	uv run pytest
 
 ruff: ## Lint with ruff
-	uv run ruff check src/
+	uv run ruff check src/ tests/
 
 ty: ## Type-check with ty
-	uv run ty check src/
+	uv run ty check src/ tests/

{exist_shell-0.1.1 → exist_shell-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exist-shell
-Version: 0.1.1
+Version: 0.2.0
 Summary: Command-line tool to interact with eXist-db via REST
 Project-URL: Homepage, https://github.com/ambs/exist-shell
 Project-URL: Repository, https://github.com/ambs/exist-shell
@@ -50,7 +50,13 @@ A command-line tool to interact with an [eXist-db](https://exist-db.org) server
 Install system-wide with `uv tool`:
 
 ```bash
-uv tool install git+https://github.com/ambs/exist-shell
+uv tool install exist-shell
+```
+
+Or with `pipx`:
+
+```bash
+pipx install exist-shell
 ```
 
 This places `exsh` on your `PATH`. Verify with:
@@ -65,6 +71,22 @@ To uninstall:
 uv tool uninstall exist-shell
 ```
 
+### Run without installing
+
+```bash
+uvx --from exist-shell exsh --version
+```
+
+`uvx` fetches the package into a temporary, cached environment and runs it — handy for one-off use or trying out a new release.
+
+### Install from git
+
+To track an unreleased commit instead of a PyPI release:
+
+```bash
+uv tool install git+https://github.com/ambs/exist-shell
+```
+
 ## Configuration
 
 ### Add a server
@@ -113,11 +135,13 @@ Configuration is stored at `~/.config/exsh/config.toml`.
 | `exsh put <file> <nick>:<path>` | Upload a local file to a collection |
 | `exsh cp <src> <dst>` | Copy a document (local ↔ remote or remote ↔ remote) |
 | `exsh edit <nick>:<path>` | Open a document in `$EDITOR`, re-upload if changed |
-| `exsh rm <nick>:<path>...` | Delete one or more documents |
+| `exsh rm <nick>:<path>...` | Delete one or more documents; `--recursive`/`-r` (with `--yes`/`-y`) to delete a collection |
 | `exsh mkdir <nick>:<path>` | Create a collection |
 | `exsh sync <local> <nick>[:<path>]` | Push a local folder to a remote collection |
 | `exsh sync <nick>[:<path>] <local>` | Pull a remote collection to a local folder |
 | `exsh exec <nick>[:<path>]` | Execute an XQuery script on a server |
+| `exsh exec --resource <nick>:<path.xql>` | Execute a stored resource in place, forwarding `-p name=value` params |
+| `exsh find <nick>[:<path>] --query <xpath>` | Find documents matching an XPath expression, with optional `--remove` |
 | `exsh server add <host>` | Register a server |
 | `exsh server ls` | List registered servers |
 | `exsh server rm <nick>` | Remove a server (and its collections) |
@@ -163,6 +187,9 @@ exsh rm mydata:reports/2025/old.xml
 # Delete multiple documents
 exsh rm mydata:reports/2025/a.xml mydata:reports/2025/b.xml
 
+# Delete a whole collection (prompts unless --yes is also given)
+exsh rm --recursive mydata:reports/2025
+
 # Create a subcollection
 exsh mkdir mydata:reports/2026
 
@@ -178,6 +205,18 @@ exsh exec mydata:/ --no-fix -f query.xq
 # List locally available XQuery validators
 exsh exec --list-validators
 
+# Execute a stored .xql/.xqm resource in place, rather than downloading it first
+exsh exec --resource mydata:/report.xql
+
+# ...forwarding query-string parameters as external variables
+exsh exec --resource mydata:/report.xql -p from=2026-01-01 -p to=2026-12-31
+
+# List documents containing a matching element anywhere in their tree
+exsh find mydata:reports --query 'foo[@type="draft"]'
+
+# Delete every match, skipping the confirmation prompt
+exsh find mydata:reports --query 'foo[@type="draft"]' --remove --yes
+
 # Push a local folder to the server (only transfers changed files)
 exsh sync ./reports mydata:reports
 
@@ -190,6 +229,9 @@ exsh sync --dry-run ./reports mydata:reports
 # Push and remove files on the server that no longer exist locally
 exsh sync --delete ./reports mydata:reports
 
+# Sync everything except temp files and the build folder (remembered for later runs)
+exsh sync --exclude '*.tmp' --exclude build ./reports mydata:reports
+
 # Change owner and group of a document
 exsh chown alice:editors mydata:reports/annual.xml
 
@@ -216,13 +258,26 @@ exsh chmod -R 0644 mydata:data
 
 **Conflicts** (both sides changed since last sync) are reported and skipped — use `--force` to override.
 
+**Excludes:** `--exclude`/`-e <pattern>` (repeatable) skips matching paths on both sides of the sync — they are neither transferred nor ever deleted by `--delete`. Patterns are `fnmatch`-style (`*`, `?`, `[seq]`), matched against the path relative to the sync root:
+
+- A pattern containing `/` matches that relative path and everything below it (`build/sub` also excludes `build/sub/x.xml`). Note that `*` in such a pattern also crosses `/` (plain `fnmatch`, unlike gitignore): `build/*.xml` matches `build/sub/x.xml` too.
+- A pattern without `/` matches any single path segment at any depth — `build` excludes `build/`, `a/build/`, and their contents; `*.tmp` excludes temp files everywhere.
+
+Patterns are persisted in the sync manifest, per (server, remote path, local folder), so later runs keep excluding without repeating the flag. New `--exclude` patterns are merged into the stored list; `--clear-exclude` wipes it (combine both to replace the list in one run). Files that were synced before becoming excluded are deleted **on both sides** after a confirmation prompt — `--yes` skips the prompt, declining (or running non-interactively without `--yes`) keeps the files, and `--keep-excluded` keeps them without asking. In every case they stop being tracked.
+
 **Options:**
 
 | Flag | Effect |
 |------|--------|
 | `--force` / `-f` | Transfer all files, bypassing change detection |
 | `--dry-run` / `-n` | Show what would happen without transferring |
+| `--fail-fast` | Stop on the first conflict, invalid XML, or transfer error (runs sequentially; the manifest is saved so the run can resume) |
+| `--jobs N` / `-j` | Number of parallel transfer workers (default: 4); `--jobs 1` for fully sequential behaviour |
 | `--delete` | Remove files and empty folders on the destination that no longer exist on the source |
+| `--exclude PATTERN` / `-e` | Skip matching paths on both sides (repeatable); merged into the list stored for this sync pair |
+| `--clear-exclude` | Wipe the stored exclude list before applying any `--exclude` given in the same run |
+| `--keep-excluded` | Keep previously synced copies of newly excluded paths; only stop tracking them |
+| `--yes` / `-y` | Skip the confirmation prompt when deleting previously synced, newly excluded files |
 | `--verbose` / `-v` | Also print unchanged (skipped) files |
 | `--checkpoint-every N` | Flush the manifest every N files (default: 100); allows interrupted syncs to resume near the point of failure |
 
@@ -241,6 +296,8 @@ exsh --install-completion zsh
 exsh --install-completion fish
 ```
 
+Upgrading? Re-run `exsh --install-completion bash` to pick up fixes to the generated script — it's written once to `~/.bash_completions/` (or equivalent) and isn't updated automatically.
+
 ## Development
 
 ```bash

{exist_shell-0.1.1 → exist_shell-0.2.0}/README.md

@@ -19,7 +19,13 @@ A command-line tool to interact with an [eXist-db](https://exist-db.org) server
 Install system-wide with `uv tool`:
 
 ```bash
-uv tool install git+https://github.com/ambs/exist-shell
+uv tool install exist-shell
+```
+
+Or with `pipx`:
+
+```bash
+pipx install exist-shell
 ```
 
 This places `exsh` on your `PATH`. Verify with:
@@ -34,6 +40,22 @@ To uninstall:
 uv tool uninstall exist-shell
 ```
 
+### Run without installing
+
+```bash
+uvx --from exist-shell exsh --version
+```
+
+`uvx` fetches the package into a temporary, cached environment and runs it — handy for one-off use or trying out a new release.
+
+### Install from git
+
+To track an unreleased commit instead of a PyPI release:
+
+```bash
+uv tool install git+https://github.com/ambs/exist-shell
+```
+
 ## Configuration
 
 ### Add a server
@@ -82,11 +104,13 @@ Configuration is stored at `~/.config/exsh/config.toml`.
 | `exsh put <file> <nick>:<path>` | Upload a local file to a collection |
 | `exsh cp <src> <dst>` | Copy a document (local ↔ remote or remote ↔ remote) |
 | `exsh edit <nick>:<path>` | Open a document in `$EDITOR`, re-upload if changed |
-| `exsh rm <nick>:<path>...` | Delete one or more documents |
+| `exsh rm <nick>:<path>...` | Delete one or more documents; `--recursive`/`-r` (with `--yes`/`-y`) to delete a collection |
 | `exsh mkdir <nick>:<path>` | Create a collection |
 | `exsh sync <local> <nick>[:<path>]` | Push a local folder to a remote collection |
 | `exsh sync <nick>[:<path>] <local>` | Pull a remote collection to a local folder |
 | `exsh exec <nick>[:<path>]` | Execute an XQuery script on a server |
+| `exsh exec --resource <nick>:<path.xql>` | Execute a stored resource in place, forwarding `-p name=value` params |
+| `exsh find <nick>[:<path>] --query <xpath>` | Find documents matching an XPath expression, with optional `--remove` |
 | `exsh server add <host>` | Register a server |
 | `exsh server ls` | List registered servers |
 | `exsh server rm <nick>` | Remove a server (and its collections) |
@@ -132,6 +156,9 @@ exsh rm mydata:reports/2025/old.xml
 # Delete multiple documents
 exsh rm mydata:reports/2025/a.xml mydata:reports/2025/b.xml
 
+# Delete a whole collection (prompts unless --yes is also given)
+exsh rm --recursive mydata:reports/2025
+
 # Create a subcollection
 exsh mkdir mydata:reports/2026
 
@@ -147,6 +174,18 @@ exsh exec mydata:/ --no-fix -f query.xq
 # List locally available XQuery validators
 exsh exec --list-validators
 
+# Execute a stored .xql/.xqm resource in place, rather than downloading it first
+exsh exec --resource mydata:/report.xql
+
+# ...forwarding query-string parameters as external variables
+exsh exec --resource mydata:/report.xql -p from=2026-01-01 -p to=2026-12-31
+
+# List documents containing a matching element anywhere in their tree
+exsh find mydata:reports --query 'foo[@type="draft"]'
+
+# Delete every match, skipping the confirmation prompt
+exsh find mydata:reports --query 'foo[@type="draft"]' --remove --yes
+
 # Push a local folder to the server (only transfers changed files)
 exsh sync ./reports mydata:reports
 
@@ -159,6 +198,9 @@ exsh sync --dry-run ./reports mydata:reports
 # Push and remove files on the server that no longer exist locally
 exsh sync --delete ./reports mydata:reports
 
+# Sync everything except temp files and the build folder (remembered for later runs)
+exsh sync --exclude '*.tmp' --exclude build ./reports mydata:reports
+
 # Change owner and group of a document
 exsh chown alice:editors mydata:reports/annual.xml
 
@@ -185,13 +227,26 @@ exsh chmod -R 0644 mydata:data
 
 **Conflicts** (both sides changed since last sync) are reported and skipped — use `--force` to override.
 
+**Excludes:** `--exclude`/`-e <pattern>` (repeatable) skips matching paths on both sides of the sync — they are neither transferred nor ever deleted by `--delete`. Patterns are `fnmatch`-style (`*`, `?`, `[seq]`), matched against the path relative to the sync root:
+
+- A pattern containing `/` matches that relative path and everything below it (`build/sub` also excludes `build/sub/x.xml`). Note that `*` in such a pattern also crosses `/` (plain `fnmatch`, unlike gitignore): `build/*.xml` matches `build/sub/x.xml` too.
+- A pattern without `/` matches any single path segment at any depth — `build` excludes `build/`, `a/build/`, and their contents; `*.tmp` excludes temp files everywhere.
+
+Patterns are persisted in the sync manifest, per (server, remote path, local folder), so later runs keep excluding without repeating the flag. New `--exclude` patterns are merged into the stored list; `--clear-exclude` wipes it (combine both to replace the list in one run). Files that were synced before becoming excluded are deleted **on both sides** after a confirmation prompt — `--yes` skips the prompt, declining (or running non-interactively without `--yes`) keeps the files, and `--keep-excluded` keeps them without asking. In every case they stop being tracked.
+
 **Options:**
 
 | Flag | Effect |
 |------|--------|
 | `--force` / `-f` | Transfer all files, bypassing change detection |
 | `--dry-run` / `-n` | Show what would happen without transferring |
+| `--fail-fast` | Stop on the first conflict, invalid XML, or transfer error (runs sequentially; the manifest is saved so the run can resume) |
+| `--jobs N` / `-j` | Number of parallel transfer workers (default: 4); `--jobs 1` for fully sequential behaviour |
 | `--delete` | Remove files and empty folders on the destination that no longer exist on the source |
+| `--exclude PATTERN` / `-e` | Skip matching paths on both sides (repeatable); merged into the list stored for this sync pair |
+| `--clear-exclude` | Wipe the stored exclude list before applying any `--exclude` given in the same run |
+| `--keep-excluded` | Keep previously synced copies of newly excluded paths; only stop tracking them |
+| `--yes` / `-y` | Skip the confirmation prompt when deleting previously synced, newly excluded files |
 | `--verbose` / `-v` | Also print unchanged (skipped) files |
 | `--checkpoint-every N` | Flush the manifest every N files (default: 100); allows interrupted syncs to resume near the point of failure |
 
@@ -210,6 +265,8 @@ exsh --install-completion zsh
 exsh --install-completion fish
 ```
 
+Upgrading? Re-run `exsh --install-completion bash` to pick up fixes to the generated script — it's written once to `~/.bash_completions/` (or equivalent) and isn't updated automatically.
+
 ## Development
 
 ```bash

{exist_shell-0.1.1 → exist_shell-0.2.0}/docs/api.md

@@ -4,6 +4,14 @@
 
 ## Installation
 
+```bash
+pip install exist-shell
+# or with uv
+uv add exist-shell
+```
+
+To track an unreleased commit instead of a PyPI release:
+
 ```bash
 pip install git+https://github.com/ambs/exist-shell
 # or with uv

{exist_shell-0.1.1 → exist_shell-0.2.0}/docs/commands.md

@@ -181,11 +181,20 @@ EDITOR=nano exsh edit mydata:config.xml
 Delete one or more documents from an eXist collection.
 
 ```
-exsh rm <nick>:<path>...
+exsh rm [--recursive] [--yes] <nick>:<path>...
 ```
 
 Multiple paths can be supplied in a single invocation. Deletion is permanent — there is no undo.
 
+A target that is itself a collection is refused by default (`Error: '<nick>:<path>' is a collection; use -r/--recursive to delete it and everything under it.`) rather than silently deleting the whole subtree. Pass `--recursive` to allow it; unless `--yes` is also given, `rm` first prompts for confirmation naming the collection being removed.
+
+### Options
+
+| Flag | Effect |
+|------|--------|
+| `--recursive / -r` | Allow a target that is a collection to be deleted, along with everything under it. |
+| `--yes / -y` | Skip the confirmation prompt when deleting a collection. |
+
 ### Examples
 
 ```bash
@@ -194,6 +203,12 @@ exsh rm mydata:reports/2025/old.xml
 
 # Delete multiple documents at once
 exsh rm mydata:reports/2025/a.xml mydata:reports/2025/b.xml
+
+# Delete a whole collection (prompts for confirmation)
+exsh rm --recursive mydata:reports/2025
+
+# Delete a whole collection without prompting
+exsh rm --recursive --yes mydata:reports/2025
 ```
 
 ---
@@ -271,6 +286,7 @@ Execute an XQuery script on an eXist-db server and print the result to stdout.
 
 ```
 exsh exec <nick>[:<path>] [-f FILE] [--no-fix] [--no-validate] [--validator NAME]
+exsh exec --resource <nick>:<path.xql> [-p NAME=VALUE ...]
 ```
 
 The query is read from `--file` or from stdin. Before sending, `exsh` optionally preprocesses the source and validates it locally:
@@ -291,10 +307,18 @@ The first installed validator found on `PATH` is used automatically. Use `--vali
 
 Run `exsh exec --list-validators` to see which validators are available on the current machine.
 
+### Executing a stored resource
+
+`--resource <nick>:<path.xql>` runs a `.xql`/`.xqm` script that's already stored on the server in place, instead of sending local source. This is a plain `GET` on the resource — the same mechanism eXist uses to execute these MIME types automatically — so it relies on the resource being invoked in its own stored collection context, which matters for scripts that assume that context (e.g. relative `doc()`/`collection()` lookups).
+
+`--resource` is mutually exclusive with the `<nick>[:<path>]` argument, and skips local preprocessing/validation entirely, since there's no local source to fix up or check. Repeat `-p/--param NAME=VALUE` to forward query-string parameters, which the resource can read as external variables.
+
 ### Options
 
 | Flag | Description |
 |------|-------------|
+| `--resource <nick>:<path.xql>` | Execute a stored resource in place instead of local code. |
+| `-p / --param NAME=VALUE` | Query-string parameter to forward with `--resource` (repeatable). |
 | `-f / --file FILE` | XQuery file to execute. When omitted, stdin is read. |
 | `--no-fix` | Skip preprocessing (version declaration, namespace imports). |
 | `--no-validate` | Skip local validation even if a validator is installed. |
@@ -324,6 +348,58 @@ exsh exec mydata:/ --validator basex -f query.xq
 
 # Check which validators are available locally
 exsh exec --list-validators
+
+# Execute a stored resource in place, rather than downloading it first
+exsh exec --resource mydata:/report.xql
+
+# ...forwarding query-string parameters as external variables
+exsh exec --resource mydata:/report.xql -p from=2026-01-01 -p to=2026-12-31
+```
+
+---
+
+## find
+
+Locate documents whose content matches an XPath expression, and optionally delete every match in one step.
+
+```
+exsh find <nick>[:<path>] --query <xpath> [--remove] [--yes]
+```
+
+The expression given to `--query` is evaluated recursively under the target collection (equivalent to `collection(...)//(QUERY)`), and each matching document is printed as a `<nick>:<path>` target — the same format `rm` and every other command accepts. Because `rm` takes its targets as arguments (not from standard input), pipe `find` output through `xargs` to feed it into `rm`:
+
+```bash
+exsh find mydata:reports --query 'foo[@type="draft"]' | xargs -r exsh rm
+```
+
+Deleting matches directly with `--remove` is usually simpler; the pipe form is useful when you want to filter the list first.
+
+Without `--remove`, `find` only lists matches — this is inherently a dry run. With `--remove`, matches are deleted as they're printed; unless `--yes` is also given, `find` first prompts for confirmation showing the number of matching documents. If a document reported by the search has already disappeared by the time it is deleted, `find` warns and continues, then exits non-zero.
+
+> **Security note:** the `--query` expression is embedded into a server-side XQuery without validation or sandboxing, so it can execute arbitrary XQuery with your configured server credentials (the same trust model as `exsh exec`). Only pass expressions from a trusted source.
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--query / -q XPATH` | XPath expression to match, evaluated recursively under the target (required). |
+| `--remove` | Delete matching documents instead of just listing them. |
+| `--yes / -y` | Skip the confirmation prompt when used with `--remove`. |
+
+### Examples
+
+```bash
+# List documents containing a matching element anywhere in their tree
+exsh find mydata:reports --query 'foo[@type="draft"]'
+
+# Match on an attribute nested deeper in the document
+exsh find mydata:/ --query 'section/foo[@type="draft"]'
+
+# Delete every match, with a confirmation prompt showing the match count
+exsh find mydata:reports --query 'foo[@type="draft"]' --remove
+
+# Delete every match, skipping the confirmation prompt
+exsh find mydata:reports --query 'foo[@type="draft"]' --remove --yes
 ```
 
 ---

{exist_shell-0.1.1 → exist_shell-0.2.0}/docs/index.md

@@ -21,7 +21,7 @@
 
 ```bash
 # 1. Install
-uv tool install git+https://github.com/ambs/exist-shell
+uv tool install exist-shell
 
 # 2. Register your server
 exsh server add localhost --port 8080 --user admin