Command line tool to interact with exist-db instances
npm install @existdb/xst
``
╲ ╱ ╓─── ──┰──
╳ ╰───╮ │
╱ ╲ ▂▁▁▁│ ┇
A modern command line interface for exist-db
`
[![version][version-image]][version-url]
[![Conventional Commits][ccommits-image]][ccommits-url]
[![javascript style guide][standard-image]][standard-url]


[version-image]: https://img.shields.io/npm/v/@existdb/xst.svg?style=flat
[version-url]: https://www.npmjs.com/package/@existdb/xst
[ccommits-image]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue?logo=conventionalcommits&logoColor=white
[ccommits-url]: https://conventionalcommits.org
[standard-image]: https://img.shields.io/badge/code_style-standard-blue.svg
[standard-url]: https://standardjs.com
Built on top of @existdb/node-exist.
Prerequisite: nodeJS version 18 or later
npm install --global @existdb/xst
This will put the executable xst in your path.
To update to the latest version of xst
`bash`
npm update --global @existdb/xst
`bash`
xst
You can verify your installation is working with
`bash`
xst --version
Output commands and options
`bash`
xst --help
You can use --help with any command to get additional information on how to use it.
`bash`
xst
Available Commands
| command | description | aliases |
|--------------------------------------------|---------------------------------------------|---------------------|
| info | Gather system information | |get [options]
| | Download a collection or resource | download fetch |upload [options]
| | Upload files and directories. | up |remove [options]
| | Remove collections or resources | rm delete del |edit [options]
| | Edit a resource in a local editor | |execute [
| | Execute a query string or file | run exec |list [options]
| | List collection contents | ls |package list [options]
| | List installed packages | pkg ls |package install
| | Install XAR packages from various sources | pkg i |package uninstall [options]
| | Remove XAR packages (does check dependents) | pkg uninstall. |
#### List collections
`bash`
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.
`bash`
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
`bash`
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.
`bash`
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.
`bash`
xst get /db/apps/dashboard .
The above downloads the contents of the collection /db/apps/dashboard into thedashboard 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.
`bash`
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.
`bash`
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.
`bash`
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
`bash`
xst package install from-registry demo-apps
##### One or more local files
`bash`
xst package install local-files path/to/*.xar
#### List all installed application packages with their dependencies
`bash`
xst package list --applications --dependencies
#### Uninstall a package
NOTE: The user initiating the command must be a member of the DBA group.
`bash`
xst package uninstall demo-apps
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.
xst now supports configuration files. The global --config option expects a path to a readable
configuration file. Currently three different formats are recognized.
Example
`bash`
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
`bash`
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.
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
If you want to test or develop this package further follow the steps below
1. clone this repository
`bash`
git clone https://github.com/line-o/xst
2. change to the working directory
`bash`
cd xst
3. install package dependencies
`bash`
npm install
4. link this package into your global packages directory
`bash`
npm link
Note: With this setup --version will always output 0.0.0-development.
Once you followed the above steps and linked a local clone of this repository
run the testsuite with
`bash`
npm test
NOTE: You will need to have an instance of existdb running (usually a local development instance).
If you want to get test code coverage information run
`bash`
npm run coverage
NOTE: You will need to have an instance of existdb running (usually a local development instance).
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
`bash`
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.
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.
If you want to check your commits while developing you can add a pre-commit-hook with
husky.
Activate husky for this project
`bash`
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.