@existdb/xst

  ╲ ╱  ╓───  ──┰──
   ╳   ╰───╮   │  
  ╱ ╲  ▂▁▁▁│   ┇  

  A modern command line interface for exist-db

Built on top of @existdb/node-exist.

Installation

Prerequisite: nodeJS version 18 or later

npm install --global @existdb/xst

This will put the executable xst in your path.

Updating

To update to the latest version of xst

npm update --global @existdb/xst

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 <command>	Install XAR packages from various sources	pkg i <command>
package uninstall [options] <packages..>	Remove XAR packages (does check dependents)	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

Installation of XAR packages

NOTE: The user initiating the command must be a member of the DBA group.

Package installation will attempt to resolve and install all dependencies declare in repo.xml. Installation will fail, if a dependency could not be found or could not be installed. The default registry (AKA public-repo) is https://exist-db.org/exist/apps/public-repo but can be overridden with the --registry option.

From a registry

xst package install from-registry demo-apps

One or more local files

xst package install local-files path/to/*.xar

List all installed application packages with their dependencies

xst package list --applications --dependencies

Uninstall a package

NOTE: The user initiating the command must be a member of the DBA group.

xst package uninstall demo-apps

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	guest	the user used to connect to the database and to execute queries with
EXISTDB_PASS	guest	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

• clone this repository

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

• change to the working directory

  cd xst
  

• install package dependencies

  npm install
  

• 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).

Coverage

If you want to get test code coverage information run

npm run coverage

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

No REST

Additional tests in spec/norest/**/*.js ensure that everything keeps working even on instances where the REST API is disabled. You can run those with

npm run test:norest

NOTE: Keep in mind they will only run successfully against an instance that actually has REST disabled. The Test - No REST GitHub Action makes use of this.

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

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.