Manage Access Control with the CLI

TerminusDB's CLI provides direct access to the role-based access control system without HTTP requests. Use it to create users, inspect roles, and grant or revoke capabilities from the command line.

List built-in roles

TerminusDB ships with two built-in roles. Inspect them before granting:

terminusdb role get

Expected output:

[
  {
    "@id": "Role/admin",
    "name": "admin",
    "action": ["branch", "class_frame", "clone", "commit_read_access", "commit_write_access", "create_database", "delete_database", "fetch", "instance_read_access", "instance_write_access", "manage_capabilities", "meta_read_access", "meta_write_access", "push", "rebase", "schema_read_access", "schema_write_access"]
  },
  {
    "@id": "Role/consumer",
    "name": "consumer",
    "action": ["class_frame", "clone", "instance_read_access", "meta_read_access", "schema_read_access"]
  }
]

To inspect a single role by name:

terminusdb role get consumer --json

Create a custom role

The built-in roles cover common cases, but you can create roles with exactly the actions you need:

terminusdb role create ROLE_NAME ACTION_1 ACTION_2 ... ACTION_N

Available actions: create_database, delete_database, class_frame, clone, fetch, push, branch, rebase, instance_read_access, instance_write_access, schema_read_access, schema_write_access, meta_read_access, meta_write_access, commit_read_access, commit_write_access, manage_capabilities

Example: a clone-only role

terminusdb role create cloner clone commit_read_access

This creates a role with the clone and commit_read_access actions — the minimum required for anonymous public access (see worked example below).

Example: a read-write role without admin powers

terminusdb role create writer instance_read_access instance_write_access schema_read_access commit_read_access commit_write_access branch rebase

To delete a custom role:

terminusdb role delete cloner

Create a user

Create a new user with a password:

terminusdb user create alice --password alice-secret

To create a user without a password (for token-based or anonymous access):

terminusdb user create anonymous

Verify the user exists:

terminusdb user get alice --json

To list all users:

terminusdb user get

Grant a capability

Grant one or more roles to a user on a specific scope (database or organisation):

terminusdb capability grant USER SCOPE ROLE

Parameters:

Options:

Example: grant read-only access to a database

terminusdb capability grant alice admin/MyDatabase consumer

Alice can now read documents and schema from admin/MyDatabase, but cannot write, branch, or delete.

Example: grant admin access to an organisation

terminusdb capability grant alice admin admin --scope-type organization

Alice now has full admin access to the admin organisation and all databases within it.

Revoke a capability

Remove one or more roles from a user on a scope:

terminusdb capability revoke USER SCOPE ROLE

The parameters and options are identical to capability grant.

Example: revoke read-only access

terminusdb capability revoke alice admin/MyDatabase consumer

Alice can no longer access admin/MyDatabase.

Verify a user's capabilities

Check what capabilities a user has:

terminusdb user get alice --capability --json

This returns the user record including all granted capabilities, their scopes, and associated roles.

Worked example: enable anonymous cloning

The most common use case for CLI access control is making a database publicly cloneable without authentication. TerminusDB has a built-in anonymous user — granting it clone permission on a database allows anyone to clone that database without credentials.

Why this matters

Public datasets, documentation examples, and template databases all need to be cloneable by anyone. Without anonymous access, every clone request requires valid credentials — which blocks use cases like:

• Documentation quickstarts that clone a pre-built dataset
• Public API servers that serve read-only data
• Template servers that distribute starter databases

Step 1 — Create a minimal cloner role

The built-in consumer role grants broader read access (fetch, schema read, instance read) than anonymous users need. Follow the principle of least privilege — create a dedicated role with only the actions required for cloning:

terminusdb role create cloner clone commit_read_access

This creates a role with exactly two actions: clone (to clone the database) and commit_read_access (required by the clone operation). Nothing else.

Verify it was created:

terminusdb role get cloner --json

Expected output:

{
  "@id": "Role/cloner",
  "name": "cloner",
  "action": ["clone", "commit_read_access"]
}

Step 2 — Confirm the database exists

terminusdb db list

You should see admin/MyDatabase (or whichever database you want to make public) in the output.

Step 3 — Grant clone access to anonymous

terminusdb capability grant anonymous admin/MyDatabase cloner

This grants the anonymous user the cloner role on admin/MyDatabase. Anonymous requests can now clone that database — and nothing else.

Step 4 — Verify the grant

terminusdb user get anonymous --capability --json

Expected output includes a capability entry linking anonymous to the cloner role on your database:

{
  "@id": "User/anonymous",
  "name": "anonymous",
  "capability": [
    {
      "@id": "Capability/...",
      "role": ["Role/cloner"],
      "scope": "admin/MyDatabase"
    }
  ]
}

Step 5 — Test anonymous cloning

From a different machine (or without credentials), clone the database:

curl -X POST http://localhost:6363/api/clone/admin/my-local-copy \
  -H "Content-Type: application/json" \
  -d '{
    "remote_url": "http://localhost:6363/admin/MyDatabase",
    "label": "My Local Copy",
    "comment": "Cloned without authentication"
  }'

No -u admin:root — the request succeeds because anonymous has clone permission via the cloner role.

Step 6 — Revoke access (if needed)

To make the database private again:

terminusdb capability revoke anonymous admin/MyDatabase cloner

Anonymous clone requests will now return 401 Unauthorized.

To remove the role entirely (if no longer needed by any user):

terminusdb role delete cloner

Quick reference

See also

• Access Control Tutorial (HTTP API) — same operations using curl
• Access Control Reference — full model: roles, actions, capability inheritance
• CLI Commands Reference — complete CLI documentation