tuscli - Independent TerminusDB Javascript document cli

Note: Tuscli was previously hoijnet/tuscli and DFRNT assumed maintainership for it since 2023-01-21.

Interact with TerminusDB and DFRNT from the commandline to import/export documents and setup the schema.

This open source tool is built to help changemakers leverage semantic knowledge graphs from the command line. We, DFRNT, believe in data mesh as a great bearer of structured organisational data. We leverage TerminusDB to build our product on. This tuscli tooling integrates TerminusDB/TerminusX data and complements the DFRNT platform.

Sign up to the DFRNT waiting list to receive your invitation to our beta. We have slowly begun the onboarding now during early 2022.

Requirements unless using a prepackaged form

• NodeJS

Usage

When running with docker and docker-compose, use the correct host, and add the docker network to connect run the command with.

$ export TUSPARAMS="$(echo '{"url":"http://localhost:6363","key":"password","user":"admin","organisation":"admin","db":"mydb"}' | base64 )"
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --help
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --export-schema
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --query-document '{"type":"Person"}'
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --read Person/johndoe
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --delete Person/johndoe
$ docker run --rm -it --network terminusdb_default -e TUSPARAMS="$TUSPARAMS" hoijnet/tuscli --instance schema --read Person

Interact with TerminusDB from the commandline to import/export documents and setup the schema.

$ export TUSPARAMS="$(echo '{"url":"http://localhost:6363","key":"password","user":"admin","organisation":"admin","db":"mydb"}' | base64 )"
$ npm install
$ node dist/tuscli.js

Build a docker image with tuscli as a binary in it, note that nexe itself takes a long time to compile.

$ docker build --pull -t tuscli -f docker/Dockerfile .
$ docker run --rm -it tuscli --help
$ echo '{ "@id": "newenum", "@type": "Enum", "@value": [ "mytest" ] }' > examples/newenum.json
$ docker run --rm -it -e TUSPARAMS="$TUSPARAMS" -v "`pwd`"/examples:/json tuscli -i schema -c /json/newenum.json

To build an executable tuscli file with embedded node.js in it:

$ npm run buildnexe
$ ./tuscli --help

Install tuscli globally on your system

$ sudo npm install -g @hoijnet/tuscli

Examples

$ node dist/tuscli.js --createBranch mybranch true
$ node dist/tuscli.js --branch mybranch --export-schema
$ node dist/tuscli.js --query-document '{"type":"Person"}'
$ node dist/tuscli.js --read Person/johndoe
$ node dist/tuscli.js --delete Person/johndoe
$ node dist/tuscli.js --instance schema --create "`pwd`/schemaDocument.json"
$ node run buildnexe
$ ./tuscli --instance schema --update Person ./person.json

To import and export, make sure that the coloring is removed from the json, and remove the TerminusDB schema preamble. Then it is possible to import the JSON array of documents with --instance schemaand --create flags. Can be helpful to try in a separate branch as well.

Additional examples can be found in the examples folder, including an example of CSV document import using WOQL.

Motivation and Features

• Load documents into TerminusDB from the cli
• Interact with schema, system and instance parts of TerminusDB from the cli
• It was easier for me to get started in Javascript 😄
• Consider using the official TerminusDB Python scaffolding cli instead, one that has these and more advanced features!

Project goals

• Make it easy to import/export schema/system/instance TerminusDB documents to/from disk
• Make it easy to interact with TerminusDB from the command line
• Show simple usage of the Javascript TermimusDB SDK
• Enable interaction with other on-disk JSON manipulation tools
• Easy of use, stability and correctness to be a higher priority than many features

tuscli options

Usage: tuscli [options]

TerminusDB Javascript cli: tuscli [options] <fileName(s)>

Options:
  -V, --version                                    output the version number
  -c, --create                                     create document from provided file
  --createFromJson                                 create document from supplied JSON, like '{"@id":"Entity/1",
                                                   "@type":"Entity"}'
  -r, --read <document-id>                         read document-id (Type/id)
  -s, --schemaFrame <document-id>                  get the schema frame for a type/subdoctype/enum
  -u, --update <document-id>                       update document
  -d, --delete <document-id>                       delete document
  -q, --query-documents <query-template-json>      list documents of type, example: {"type":"Person"}
  -e, --export-schema                              export/show instance schema JSON
  -p, --profile <json-file>                        JSON-formatted connection profile, or set env TUSPARAMS in base64
                                                   encoding
  -z, --dump-profile                               show the default or current connection profile, and how to set it
  -o, --optimize <main>                            optimize and do delta rollups on a branch
  --createDatabase <dataproduct-id> <create-json>  create data product, default JSON: {"schema":true, "label": "",
                                                   "comment":""}
  --deleteDatabase <dataproduct-id>                delete database/data product
  --deleteDocumentsOfType <type>                   delete all documents of a type
  --deleteDocumentsIsaType <type>                  delete documents that are is-a type
  --dataProduct <dataproduct-id>                   override dataproduct to use
  --createBranch <branch-id> <true/false>          create branch, true for empty branch
  --deleteBranch <branch-id>                       delete branch
  --branches                                       pull list of branches in the data product
  --nocolor                                        disable the colorize filter of output
  --quiet                                          disable diagnostic outputs
  -x, --system                                     connect to system database
  -y, --commitGraph <count>                        get the 10 last commits, supply an argument for more
  -i, --instance <instance|schema>                 document instance, default is instance
  -b, --branch <branch-id>                         use/select active branch
  -t, --commit <commit-id>                         use/select specific commit
  --woql <WOQL>                                    Execute JS WOQL query (as an argument)
  --compileWoql <WOQL>                             Compile JS WOQL (as an argument) into JSON WOQL
  --woqlFile <example.woql.js>                     Execute JS WOQL (from a file)
  --woqlCompile <example.woql.js>                  Compile JS WOQL into JSON WOQL (from a file)
  -h, --help                                       display help for command

Contributing

This is an independent single-contributor project (so far) done in my free time so issues may take time to get resolved (pull requests get issues resolved the fastest).

• Clone hoijnet/tuscli
• Share a pull request on hoijnet/tuscli
• Open an issue on Github hoijnet/tuscli

What needs help

• Identify missing features and file issues
• Usability/naming of the cli user interface (early feedback)
• Usage examples (scripts with documents)
• Make it more robust, this is an early version!

Howto release new version and ensure all builds work first

To put into a Makefile at some point

# Bump version number in package.json
$ npm run buildnexe
$ npm run dockerize
$ git push
$ npm push
$ docker push hoijnet/tuscli

How to build a self-contained command line binary with bun

bun build ./src/tuscli.ts --compile --outfile tuscli

Dependencies and mentions

• Thanks to the great folks at TerminusDB for exciting open source technology
• Thanks to debug used for debug output
• Thanks to commander used for options parsing