xst [ĭg-zĭst′]

A modern command line interface for exist-db

Built on top of @existdb/node-exist.

Installation

Prerequisite: nodeJS version 14.18 or later

npm install --global @existdb/xst

This will put the executable xst in your path.

Usage

xst <command>

You can verify your installation is working with

xst --version

Output commands and options

xst --help

You can use --help with any command to get additional information on how to use it.

xst <command> --help

Available Commands

command	description	aliases
info	Gather system information
get [options] <source> <target>	Download a collection or resource	download fetch
upload [options] <source> <target>	Upload files and directories	up
remove [options] <paths..>	Remove collections or resources	rm delete del
edit [options] <resource>	Edit a resource in a local editor
execute [<query>] [options]	Execute a query string or file	run exec
list [options] <collection>	List collection contents	ls
package list [options]	List installed packages	pkg ls
package install [options] <packages..>	Install XAR packages	pkg i
package uninstall [options] <packages..>	Remove XAR packages	pkg uninstall

Examples

List collections

xst list /db

List the entire contents of the apps collection

This will output extended and colored information of all collections and resources of /db/apps in a tree.

xst list /db/apps --long --tree --color

NOTE: Resources and collections the connecting user does not have access to will be omitted with --long.

Find the largest JavaScript resource

xst list /db/apps --long --recursive --color --glob '*.js' --sizesort

Download a resource

This will download the controller of the dashboard to the current working directory.

xst get /db/apps/dashboard/controller.xql .

Download a collection

If the target is a collection, a folder with the same name will be created at the specified target and all of its contents will be downloaded.

xst get /db/apps/dashboard .

The above downloads the contents of the collection /db/apps/dashboard into the dashboard folder in the current working directory.

Set the permission for a resource

This demonstrates how you can extend the current functionality by running arbitrary scripts. You need to connnect as a database administrator to be able to run the queries.

xst execute 'sm:chmod(xs:anyURI($file), $permissions)' \
  -b '{"file": "/db/apps/dashboard/controller.xql", "permissions": "rwxrwxr-x"}'

Reset the permissions back to their original state.

xst execute 'sm:chmod(xs:anyURI($file), $permissions)' \
  -b '{"file": "/db/apps/dashboard/controller.xql", "permissions": "rwxr-xr-x"}'

Executing a main module

If you find yourself using the same query over and over again or it is a complex one you can save it to a file and use the --file parameter.

xst execute --file my-query.xq

Install a local XAR package into an exist-db.

This will also install all of its declared dependencies from the configured repository.

xst package install path/to/my-package.xar

NOTE: User that connects must be a database administrator.

List all installed application packages with their dependencies

xst package list --applications --dependencies

Configuration

By default xst connects to https://localhost:8443 as user guest.

NOTE: The instance you want to connect to must be running and XML-RPC has to be enabled.

With a Configuration File

xst now supports configuration files. The global --config option expects a path to a readable configuration file. Currently three different formats are recognized.

Example

xst ls /db/apps --config spec/fixtures/.xstrc 

.xstrc

A JSON formatted file where you can set connection options as well as other preferred settings like color or timesort. Have a look at the example .xstrc.

NOTE: The boolean option "secure" is deprecated. To switch between encrypted and unencrypted connections use "protocol" instead. "secure" will continue to work for both XMLRPC and REST until version 2.

.existdb.json

These are present in projects using the sync feature from eXistdb's Visual Studio Code plugin.

dotenv files

EXISTDB_USER=admin
EXISTDB_PASS=my super secret p455w0rd!
EXISTDB_SERVER=http://localhost:8080

NOTE: If the current working directory contains an .env file it will be loaded automatically unless the --config parameter is set.

With Environment Variables

Override any of the default connection parameters by setting environment variables prefixed with EXISTDB. In the following table you see a list of the parameters with their default values and a description.

variable name	default	description
EXISTDB_USER	admin	the user used to connect to the database and to execute queries with
EXISTDB_PASS	empty	the password to authenticate the user against the database
EXISTDB_SERVER	https://localhost:8443	the URL of the database instance to connect to (only http and https protocols are allowed)

Example

EXISTDB_SERVER=http://127.0.0.1:8080 xst ls /db/apps

Development

If you want to test or develop this package further follow the steps below

1. clone this repository

   git clone https://github.com/line-o/xst

2. change to the working directory

   cd xst

3. install package dependencies

   npm install

4. link this package into your global packages directory

   npm link

Note: With this setup --version will always output 0.0.0-development.

Testing

Once you followed the above steps and linked a local clone of this repository run the testsuite with

npm test

NOTE: You will need to have an instance of existdb running (usually a local development instance).

Contributing

We are happy to accept contributions from the community. Contributions can be just a typo in the readme or better documentation, as well as bugfixes and new features. For bugfixes and features it is best to open an issue, so that we can discuss your approach first. That way your PR will be merged quickly.

When committing to this project each commit message must conform to conventional commits as versioning and releases are automated using semantic-release.

commitlint

If you want to check your commits while developing you can add a pre-commit-hook with husky.

Activate husky for this project

npx husky install

This will add to git hooks

• pre-commit npm run lint ensures any JS is formatted correctly and will prevent you from committing when it encounters problems like unused variables and such.
• commit-msg will run commitlint to ensure the commit message is following conventional commit message format

These are not activated by default as it prevents you from doing work-in-progress commits. But keep in mind, both checks will run when you open a PR, so it might be easier to have this checked right from the start and not having to edit your history later.