@hoijnet/tuscli
v0.2.3
Published
TerminusDB Javascript CLI
Downloads
49
Readme
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
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 schema
and --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