TerminusDB Logo all white svg
Close this search box.

TerminusDB from the Command Line: introducing tdb-cli

by Gavin and Guest Author Matthijs van Otterdijk

This blog introduces our new command line tool for interacting with TerminusDB, whether it be local or remote. The aim, eventually, is to enable an easy to use command line client to carry out any of the operations that are possible with TerminusDB, allowing fast interactive development for those just getting started, for tool chains which include other tools, or for experts that just want a quick one-liner rather than a script to perform some operation.

The tool (written by Matthijs) is written in TypeScript. We wanted to e a bit more structured in our development than javascript gives you, and we enjoyed the assistance that can be provided in interactive development by the type checker.

We will give a quick tour of the basics.

Start a new TerminusDB instance using docker

To start a new TerminusDB you can install docker and run the following:

					docker run --rm -p 6363:6363 \
--pull always -d -v ./storage:/app/terminusdb/storage \
--name terminusdb terminusdb/terminusdb-server

This will get a new version of TerminusDB and launch it with the name terminusdb`. Note, that it will create a storage directory called storage` in the directory in which you currently reside! This will be here your databases are kept (in case you want to start another TerminusDB later with the same data).

Install tdb-cli

To get started with `tdb-cli`, we first have to install it! Assuming you have npm installed, this is simply:

					npm install -g @terminusdb/tdb-cli

Now we are ready for action…

Configure tdb-cli

To configure `tdb-cli` you can run the interactive setup in a shell:

					tdb-cli setup

If you’re starting with a new TerminusDB installation, you’ll want to fill in the questionnaire roughly as follows. Alter to suit your environment!

					Welcome to tdb-cli, the CLI tool for TerminusDB!

This setup will ask a few questions to generate your configuration.
This configuration file will be stored at /home/matthijs/.tdb.yml.

? What instance of TerminusDB do you intend to connect to? Self-hosted TerminusDB
? What name do you wish to use for this server? local
? Server endpoint URL: http://localhost:6363
? Username: admin
? Password: root
? Default organization (blank if none): admin
Configuration has been written to /home/matthijs/.tdb.yml. You are all set!


Note: If this is a new installation, you’ll want to use the password `root` since this is what TerminusDB comes with as a default admin password out of the box.

Immediately change password

Since root isn’t a great password, you’ll probably want to start by changing it:

					tdb-cli user set-password

This will update both the server and your configuration.

Create a database

Next we can create our first database:

					tdb-cli db create family

Add a schema

And we can now get the default (nearly empty) schema out:

					tdb-cli doc get family -g schema > schema.json

We can then add the following to this schema (with our favourite editor):

  "@type": "Class",
  "@id": "Person",
  "@key": {"@type": "Lexical",
           "@fields": ["name"]},
  "name": "xsd:string"


This defines a `Person` class, in which each `Person` has a name. The ids of the objects are constructed with a lexical naming scheme based on their name (the {“@type”: “Lexical”, “@fields”: “name”]} part), which makes remembering the ID of a document easier, and bars the creation of duplicates.

Now we can put our schema into the database:

					tdb-cli doc insert family -f -g schema < schema.json

Here the `-f` flag tells us we are wiping out the entire schema to replace with the data we are currently inserting (it’s like a delete/insert). The `-g` says that we are altering the schema, rather than the instance graph (where normal data resides).

Adding data under schema control

Once we have a basic schema we can start adding data:

					tdb-cli doc insert family -d '{"name": "Alice"}'
tdb-cli doc insert family -d '{"name": "Arthur"}'
tdb-cli doc insert family -d '{"name": "Bella"}'
tdb-cli doc insert family -d '{"name": "Briana"}'
tdb-cli doc insert family -d '{"name": "Bob"}'
tdb-cli doc insert family -d '{"name": "Clara"}'


This adds a number of people to the database. Note the use of `-d`, which specifies the data on the command line as a JSON string, rather than taking it from standard input. You could instead take it from standard in as follows:

					tdb-cli doc insert family <<EOF
{"name": "Carl"}


Change the schema

We can also change the definition of a person in the schema, as long s the change is compatible with the data we’ve added (in fact we can also do it if it is incompatible with a schema migration, but that’s a different story).

Edit the `schema.json` and alter the `Person` record to be as follows:

  "@key": {"@fields": ["name" ], "@type":"Lexical"},
  "child_of": {"@class":"Person", "@type":"Set"},

This definition adds a relationship between people. You can now be the child_of two other `Person`s.

					tdb-cli doc insert family -f -g schema < schema.json

Create a graph

Now we can add some more graph-like data, which uses this `child_of` relationship:

					tdb-cli doc replace family -d '{"name": "Bella", "child_of": ["Person/Alice", "Person/Arthur"]}'
tdb-cli doc replace family -d '{"name": "Briana", "child_of": ["Person/Alice", "Person/Arthur"]}'
tdb-cli doc replace family -d '{"name": "Clara", "child_of": ["Person/Bella", "Person/Bob"]}'


Launch GraphQL

Now that we have some graphy data, we can launch GraphQL

					tdb-cli graphql serve family -o

This takes you to your browser with a GraphQL endpoint attached to our database!

Fun queries

And now we can try some fun queries!

Get all people

					query {
  Person {


Get Bella and her parents

					query {
  Person(filter:{name:{eq: "Bella"}}) {
    child_of { name }


Get the children of Arthur

					query {
  Person(filter:{name:{eq: "Arthur"}}) {
    _child_of_of_Person {


Get all ancestors of Clara

					query {
  Person(filter:{name:{eq: "Clara"}}) {
      _path_to_Person(path:"child_of*") {



Latest Stories