exsh — eXist-db Shell

A command-line tool to interact with an eXist-db server via its REST API. Designed for shell scripting and pipe-friendly workflows.

Requirements

• Python 3.11+
• uv

Installation

Install system-wide with uv tool:

uv tool install exist-shell

Or with pipx:

pipx install exist-shell

This places exsh on your PATH. Verify with:

exsh --version

To uninstall:

uv tool uninstall exist-shell

Run without installing

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:

uv tool install git+https://github.com/ambs/exist-shell

Configuration

Add a server

exsh server add localhost --port 8080 --user admin

A nickname is derived from the hostname by default (e.g. localhost). Override with --nick.

Add an existing collection

exsh collection add mydata@localhost

This registers the /db/mydata collection on the localhost server under the nick mydata.

Create and register a new collection

exsh collection new mydata@localhost

Creates /db/mydata on the server and registers it in one step. If the collection already exists, it prints a message and exits without modifying the config. Use --nick to register it under a different name:

exsh collection new mydata@localhost --nick md

List configured servers and collections:

exsh server ls
exsh collection ls

Configuration is stored at ~/.config/exsh/config.toml.

Commands

Examples

# List the root of a collection
exsh ls mydata

# List a subdirectory
exsh ls mydata:reports/2025

# Print a document
exsh cat mydata:reports/2025/summary.xml

# Upload a file
exsh put report.xml mydata:reports/2025/report.xml

# Copy from remote to local
exsh cp mydata:reports/2025/report.xml ./report.xml

# Edit in place
exsh edit mydata:reports/2025/report.xml

# Delete a document
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

# Execute an XQuery script from a file
exsh exec mydata:/ -f query.xq

# Execute an XQuery script from stdin
echo 'count(collection("/db/mydata"))' | exsh exec mydata:/

# Execute without local preprocessing
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

# Pull a remote collection to a local folder
exsh sync mydata:reports ./reports

# Preview what would be transferred without doing it
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

# Recursively reassign a collection tree
exsh chown -R alice mydata:reports

# Set permissions with octal mode
exsh chmod 0644 mydata:reports/annual.xml

# Add execute permission for the owner
exsh chmod u+x mydata:scripts/run.xq

# Recursively set permissions for a collection
exsh chmod -R 0644 mydata:data

Sync

exsh sync transfers only files that have changed, using a local manifest stored at ~/.cache/exsh/sync/. Direction is inferred from the argument order: local-first means push, remote-first means pull.

Change detection:

• Push: SHA-256 hash of the local file is compared against the manifest. Same-size edits are caught.
• Pull: last_modified timestamp from the eXist listing is compared against the manifest.

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:

Shell completion

Generate and install tab-completion for your shell:

# bash
exsh --install-completion bash

# zsh
exsh --install-completion zsh

# fish
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

git clone https://github.com/ambs/exist-shell
cd exist-shell
uv sync
exsh --help

Run checks:

make checks   # lint, type-check, and tests
make test     # tests only