Using TypeDB Console

 
TypeDB Console is a standalone TypeDB client with a command line interface (CLI). It serves as a lightweight and powerful CLI tool to manage and query TypeDB databases.

It is the default client distributed with TypeDB, but it can also be installed separately.

GitHub

The GitHub repository with the source code and release notes.

Downloads

See the Console’s downloadable packages.

Install

Make sure Java 11+ is installed. TypeDB Console supports OpenJDK and Oracle JDK.

Java dependency is expected to be removed in 2025.

For installation instructions, follow the steps below for your OS:

macOS
Linux
Windows

Download the latest package for your system architecture: x86_64 / arm64

For other versions, see the Downloads repository page.

Extract the archive into a new directory:

$ sudo mkdir /opt/typedb-console
$ unzip ~/Downloads/<filename>.zip -d /opt/typedb-console

Where <filename> is the name of the archive.

Add a symlink to the TypeDB Console executable in the /usr/local/bin directory:
```
$ ln -s /opt/typedb-console/<filename>/typedb /usr/local/bin/typedb
```

Download the latest package for your system architecture: x86_64 / arm64

For other versions, see the Downloads repository page.

Extract the archive into a new directory:

$ mkdir /opt/typedb-console
$ tar -xzf ~/Downloads/<filename>.tar.gz -C /opt/typedb-console

Where <filename> is the name of the archive.

Add a symlink to the TypeDB Console executable in the /usr/local/bin directory:
```
$ ln -s /opt/typedb-console/<filename>/typedb /usr/local/bin/typedb
```

Download the latest package for your system architecture: x86_64

For other versions, see the Downloads repository page.

Extract the archive into a new directory:

$ mkdir "C:\Program Files\TypeDB Console"
$ tar xvf "C:\Users\username\Downloads\<filename>.zip" -C "C:\Program Files\TypeDB Console"

Where <filename> is the name of the archive.

Update the PATH environment variable:

$ setx /M PATH "%path%;C:\Program Files\TypeDB Console\<filename>"

Restart the terminal window for the changes to environment variables to take effect.

Connect to TypeDB

TypeDB Console can connect to all editions of TypeDB. Running TypeDB Console initiates a network connection to a TypeDB server. Use command line arguments to set connection parameters (if unset it will try to connect to a TypeDB Community Edition server at the address localhost:1729):

Cloud / Enterprise
Community Edition

Connect to TypeDB Cloud or TypeDB Enterprise

typedb console --cloud=<server-address> --username=<username> --password --tls-enabled=true

You will be prompted for a password.

The --cloud argument is used to set the TypeDB Cloud server address and port to connect to, for example, https://abcdef-0.cluster.typedb.com:80.

Connect to TypeDB Community Edition

typedb console --core=<server-address> --username=<username> --password

You will be prompted for a password.

The --core argument is used to set the TypeDB Community Edition server IP address and port to connect to, for example, 10.0.0.5:1729.

The default username and password are admin and password. After connecting for the first time, you will be able to change the password.

As a result, you get a welcome message from TypeDB Console followed by a command line prompt.

Welcome to TypeDB Console. You are now in TypeDB Wonderland!
Copyright (C) Vaticle

>

See full list of available CLI arguments in the Console CLI arguments reference section below.

Interactive mode

TypeDB Console provides two levels of interaction via Read–eval–print loop (REPL): Server level and Transaction level.

At any level you can use common commands: help, clear, exit.

Server level

Server level is the first level of interaction, i.e., first-level REPL. From this level, you can use commands for managing databases and users on the server. You also can open a transaction to a database, which gets you to the second level of REPL.

For a full list of commands on the Server level, see the Server level commands section.

Transaction level

Transaction level is the second level of interaction, i.e., second-level REPL. You can control a transaction and send queries in the transaction.

For a full list of commands on the Transaction level, see the Transaction level reference section.

To send a query, while in Transaction level, type in or insert a TypeQL query and push Enter twice.

When opening a transaction, you can specify transaction options. For a full list of transaction options, see the Transaction options.

Example

The following example illustrates how to create a database, define a schema, and insert some data into the database.

Run Console in the interactive mode and connect it to TypeDB:
```
typedb console --username=<username> --password
```
Now, run the following command to create a database:
```
database create sample_db
```
To define a schema, run the transaction command to open a schema transaction to the database. This command opens a Transaction level REPL. Use it to send a define query and commit changes:
```
transaction sample_db schema
define entity user;
commit
```
To send a query in the Transaction level, push Enter twice, as a single push of the Enter is recognized as a line break in the query.

Insert data with a write transaction:

transaction sample_db write
insert $u isa user;
commit

The above example creates a database with the name sample_db, defines a simple schema with a single user type, then inserts a single instance of the type into the database.

Non-interactive mode

You can run Console commands using the --command argument:

typedb console --command=<command1> --command=<command2>

The following example achieves the same results as the one in the interactive mode via the command line arguments. Run the following command in a terminal to start TypeDB and execute queries:

typedb console --username=<username> --password \
--command="database create sample_db" \
--command="database list" \
--command="transaction sample_db schema" \
--command="define entity user;" \
--command="commit" \
--command="transaction sample_db write" \
--command='insert $u isa user;' \
--command="commit"

See the output

Output

+ database create sample_db
Database 'sample_db' created
+ database list
sample_db
test
+ transaction sample_db schema
++ define entity user;
Success
++ commit
Transaction changes committed
+ transaction sample_db write
++ insert $u isa user;
Finished validation and compilation...
Finished writes. Streaming answers...

   --------
    $u | iid 0x1e00000000000000000000 isa user
   --------

Finished. Total answers: 1

Scripting

You can create a script file that contains the list of commands to run. These are the very same commands that are used in the Interactive mode or Non-interactive mode. For the full list of commands, see the References below.

To use a script file with commands, run Console with the --script argument and a path to the script file:

typedb console --script=<script-file-path>

Each line in the script file is interpreted as one command, so multiline queries are not available in this mode. You can overcome this limitation, by calling a TypeQL query from a file with the source command. For example, see the Run a query from a file section below.

Prepare the script to run and save it to a local file. For example, let’s try the following script.txt file:

script.txt

database create test
transaction test schema
    define entity user owns name; attribute name value string;
    commit
transaction test write
    insert $u isa user, has name "Bob";
    commit
transaction test read
    match $u isa user, has name $n; select $n;
    close
database delete test

Execute the script with TypeDB Console:

Run script.txt

typedb console --username=<username> --password --script=<PATH/script.txt>

Where <PATH/script.txt> is the path to the file and the filename.

See the output

Output

+ database create test
Database 'test' created
+ transaction test schema
++ define entity user owns name; attribute name value string;
Success
++ commit
Transaction changes committed
+ transaction test write
++ insert $u isa user, has name "Bob";
Finished validation and compilation...
Finished writes. Streaming answers...

   --------
    $u | iid 0x1e00000000000000000000 isa user
   --------

Finished. Total answers: 1
++ commit
Transaction changes committed
+ transaction test read
++ match $u isa user, has name $n; select $n;
Finished validation and compilation...
Streaming answers...

   --------
    $n | Bob isa name
   --------

Finished. Total answers: 1
++ close
Transaction closed
+ database delete test
Database 'test' deleted

Run a query from a file

To run a TypeQL query stored in a file, use the source <filename> command. This command is available from the Transaction level REPL:

Interactive mode source usage example

transaction sample_db schema
source schema.tql
commit

The schema.tql file should be located in the working directory, when you run TypeDB Console, and contain a valid define query.

Script using query files examples

For example, let’s use the following script file to:

Create the sample_db database
Load the schema form the schema.tql file in a schema transaction
Load sample data from the data.tql file in a write transaction
Run a match-fetch query
Delete the database to reset the environment

Script file

database create sample_db
transaction sample_db schema
    source schema.tql
    commit
transaction sample_db write
    source data.tql
    commit
transaction sample_db read
    match $u isa user; fetch { "user": { $u.* } };
    close
database delete sample_db

See the schema.tql

schema.tql

define
  entity content @abstract,
    owns id @key;

  entity page @abstract, sub content,
    owns page-id,
    owns name,
    owns bio,
    owns profile-picture,
    plays posting:page,
    plays following:page;

  entity profile @abstract, sub page,
    owns username,
    owns name @card(0..3),
    plays group-membership:member,
    plays location:located,
    plays content-engagement:author,
    plays following:follower;

  entity user sub profile,
    owns email,
    owns phone @regex("^\d{8,15}$") @unique,
    owns karma,
    owns relationship-status,
    plays friendship:friend,
    plays family:relative,
    plays relationship:partner,
    plays marriage:spouse,
    plays employment:employee;

  relation social-relation @abstract,
    relates related @card(0..);

  relation friendship sub social-relation,
    relates friend as related @card(0..);

  relation family sub social-relation,
    relates relative as related @card(0..1000);

  relation relationship sub social-relation,
    relates partner as related,
    owns start-date;

  relation marriage sub relationship,
    relates spouse as partner,
    owns exact-date,
    plays location:located;

  entity organisation sub profile,
    owns tag @card(0..100),
    plays employment:employer;

  entity company sub organisation;
  entity charity sub organisation;

  relation employment,
    relates employer,
    relates employee,
    owns start-date,
    owns end-date;

  entity group sub page,
    owns group-id,
    owns tag @card(0..100),
    plays group-membership:group;

  relation group-membership,
    relates group,
    relates member,
    owns start-timestamp,
    owns end-timestamp;

  entity post @abstract, sub content,
    owns post-id,
    owns post-text,
    owns creation-timestamp @range(1970-01-01T00:00:00..),
    owns tag @card(0..10),
    plays posting:post,
    plays commenting:parent,
    plays reaction:parent,
    plays location:located;

  entity text-post sub post;

  entity image-post sub post,
    owns post-image;

  entity comment sub content,
    owns comment-id,
    owns comment-text,
    owns creation-timestamp,
    owns tag @card(0..5),
    plays commenting:comment,
    plays commenting:parent,
    plays reaction:parent;

  relation interaction @abstract,
    relates subject @abstract,
    relates content;

  relation content-engagement @abstract, sub interaction,
    relates author as subject;

  relation posting sub content-engagement,
    relates page as content,
    relates post @card(0..1000);

  relation commenting sub content-engagement,
    relates parent as content,
    relates comment;

  relation reaction sub content-engagement,
    relates parent as content,
    owns emoji @values("like", "love", "funny", "surprise", "sad", "angry"),
    owns creation-timestamp;

  relation following,
    relates follower,
    relates page;

  entity place,
    owns place-id,
    owns name,
    plays location:place;

  entity country sub place,
    plays city-location:parent;

  entity city sub place,
    plays city-location:city;

  relation location,
    relates place,
    relates located;

  relation city-location sub location,
    relates parent as place,
    relates city as located;

  attribute id @abstract, value string;
  attribute page-id @abstract, sub id;
  attribute username sub page-id;
  attribute group-id sub page-id;
  attribute post-id sub id;
  attribute comment-id sub id;
  attribute place-id sub id;

  attribute name value string;
  attribute email value string @regex("^.*@\w+\.\w+$");
  attribute phone value string;
  attribute karma value double;
  attribute relationship-status value string @values("single", "married", "other");
  attribute latitude value double;
  attribute longitude value double;

  attribute event-date @abstract, value datetime;
  attribute start-date sub event-date;
  attribute end-date sub event-date;
  attribute exact-date @abstract, sub event-date;

  attribute payload @abstract, value string;
  attribute text-payload @abstract, sub payload;
  attribute image-payload @abstract, sub payload;
  attribute bio sub text-payload;
  attribute comment-text sub text-payload;
  attribute post-text sub text-payload;
  attribute post-image sub image-payload;
  attribute profile-picture sub image-payload;

  attribute tag value string;
  attribute emoji value string;

  attribute creation-timestamp value datetime;
  attribute start-timestamp value datetime;
  attribute end-timestamp value datetime;

  fun all_relatives($user: user) -> { user }:
    match
      $relative isa user;
      {
        family (relative: $user, relative: $relative);
      } or {
        let $intermediate in all_relatives($user);
        family (relative: $intermediate, relative: $relative);
      };
      return { $relative };

See the data.tql

data.tql

Make sure you have the above script file and tql files saved to the working directory. Run the script with TypeDB Console using the --script argument, as you did before in the script example.

See the output

Output

+ database create sample_db
Database 'sample_db' created
+ transaction sample_db schema
++ source schema.tql
Finished writes
++ commit
Transaction changes committed
+ transaction sample_db write
++ source data.tql
Finished writes
++ commit
Transaction changes committed
+ transaction sample_db read
++ match $u isa user; fetch { "user": { $u.* } };
Finished validation and compilation...
Streaming documents...

{
    "user": {
        "email": "bob@typedb.com",
        "username": "Bob"
    }
}
{
    "user": {
        "email": "alice@typedb.com",
        "username": "Alice"
    }
}

Finished. Total answers: 2
++ close
Transaction closed
+ database delete sample_db
Database 'sample_db' deleted

Troubleshooting

Non-ASCII characters

TypeDB can use type and variable labels and store string value attributes that have characters outside the ASCII range, for example, non-English letters, symbols, and emojis. To manipulate them using Console, the Console’s terminal must use a locale with a compatible code set, such as Unicode.

If it doesn’t, these characters will most likely be rendered as ? symbols in Console. If this issue occurs, you can use the following fix:

Linux
macOS
Windows

Use locale -a to list all installed locales, and use export to set the environment. For example, to use en_US.UTF-8 run:

bash export LANG=en_US.UTF-8 && export LC_ALL=en_US.UTF-8

Use locale -a to list all installed locales, and use export to set the environment. For example, to use en_US.UTF-8 run:

bash export LANG=en_US.UTF-8 && export LC_ALL=en_US.UTF-8

Use Windows Terminal or run chcp in the terminal (e.g., chcp 936 for Chinese text).

Most systems also allow us to set the system-wide locale. However, this impacts the appearance of other applications.

References

Console CLI arguments

The following arguments can be used when invoking TypeDB Console:

Table 1. Command line arguments
Argument	Alias	Description
TypeDB Community Edition specific
`--core=<address>`		Address to which Console will connect to: IP address and IP port separated by colon. Default value: `localhost:1729`. (TypeDB Community Edition only)
TypeDB Cloud / Enterprise specific
`--cloud=<address>`		Address to which Console will connect to. (TypeDB Cloud / Enterprise only)
Common
`--help`	`-h`	Show help message.
`--username=<username>`		Username.
`--password`		Enable a password prompt.
`--tls-enabled`		Whether to connect with TLS encryption.
`--tls-root-ca=<path>`		Path to the TLS root CA file.
`--command=<commands>`		Commands to run in the Console, without interactive mode.
`--script=<script>`		Script with commands to run in the Console, without interactive mode.
`--version`	`-V`	Print version information and exit.
`--diagnostics-disable=true`		Disable anonymous error reporting.

Server level commands

Use these commands at the Server level of TypeDB’s REPL:

Table 2. Server level commands (first level of REPL)
Command	Description
Database management
`database create <db>`	Create a database with the name `<db>` on the server.
`database list`	List all databases on the server.
`database delete <db>`	Delete a database with the name `<db>` from the server.
User management
`user list`	List all users on the server.
`user create <username>`	Create a user with the name `<username>` on the server.
`user password-update <username> [new-password]`	Set password for the user with the name `username`.
`user delete <username>`	Delete a user with the name `<username>` on the server.
Open a transaction
`transaction <db> read⎮write⎮schema [options]`	Start a transaction to the database with the name `<db>` with a chosen transaction type. You can set transaction options.
Common
`help`	Print help menu.
`clear`	Clear console screen.
`exit`	Exit console.

Transaction level commands

Use these commands in the Transaction level of TypeDB Console’s REPL. The prompt at the Transaction level contains the database name and the transaction type, for example, sample_db::read>.

Table 3. Transaction level commands (second level of REPL)
Command	Description
Querying
`<query>`	Type in TypeQL query directly. Push Enter once for a line break in a query. Push Enter twice (once more on a new line) to send a query.
`source <file>`	Run TypeQL queries from a file. You can use a relative or absolute path. On Windows escape `\` by writing `\\`.
Transaction control
`commit`	Commit the changes and close the transaction.
`rollback`	Rollback the transaction — remove any uncommitted changes, while leaving the transaction open.
`close`	Close the transaction without committing changes.
Common
`help`	Print help menu.
`clear`	Clear console screen.
`exit`	Exit console.

Transaction options

Coming soon.

Version Compatibility

For older TypeDB versions, you’ll need a compatible version of TypeDB Console. Select the correct TypeDB Console version from the version compatibility table, and download it from Cloudsmith.

Version compatibility table

TypeDB Console	TypeDB	TypeDB Community Edition
3.0.2	3.0.0 to 3.0.2	3.0.0 to 3.0.2

TypeDB Console

TypeDB

TypeDB Community Edition

3.0.2

3.0.0 to 3.0.2

Services

Platform

Tools

What is TypeDB?

Try cloud free

Pricing and plans

Learn

Community

Learn

Content

Using TypeDB Console

Install

Connect to TypeDB

Interactive mode

Server level

Transaction level

Example

Non-interactive mode

Scripting

Run a query from a file

Script using query files examples

Troubleshooting

Non-ASCII characters

References

Console CLI arguments

Server level commands

Transaction level commands

Transaction options

Version Compatibility