Managing DataTables in the CLI

For the full index of agent-friendly pages, see llms.txt.

In the mabl CLI, you can programmatically list, query, create, update, and export DataTables from your workspace. This article highlights mabl CLI commands that are useful for managing DataTables.

Note: For a full list of commands and options, see the mabl CLI command reference.

Viewing DataTables

Use the following commands to get information about DataTables:

# Get a list of DataTables and their IDs
$ mabl datatables list

# Get DataTable metadata
$ mabl datatables describe {datatable-id}

# List scenario names
$ mabl datatables scenarios {datatable-id}

# Review the DataTable contents locally
$ mabl datatables export {datatable-id}

Creating DataTables

Use mabl datatables create to create a DataTable from a JSON or CSV file. The file input should be a relative path to the file you are using to create the DataTable.

On creating the DataTable, the mabl CLI returns details on the new DataTable, including workspace ID, name of DataTable, scenario IDs, time created and by whom, time last updated and by whom.

For example:

# Create a DataTable from a JSON file 
$ mabl datatables create login_check.json --name "Login check" 

# Create a DataTable from a CSV file and name it "Sample data" 
$ mabl datatables create samples.csv --name "Sample data"

Sample file input

File input must be either JSON or CSV.

JSON

[
    {
      "name": "English",
      "variables": [
        {
          "name": "login",
          "value": "Login"
        },
        {
          "name": "greeting",
          "value": "Welcome back"
        },
        {
          "name": "logout",
          "value": "Logout"
        }
      ]
    },
    {
      "name": "Spanish",
      "variables": [
        {
          "name": "login",
          "value": "Iniciar sesión"
        },
        {
          "name": "greeting",
          "value": "Qué bueno verte de nuevo"
        },
        {
          "name": "logout",
          "value": "Cerrar sesión"
        }
      ]
    }
  ]

CSV

Scenario name, login, greeting, logout
English, Login, Welcome back, Logout
Spanish, Iniciar sesión, Qué bueno verte de nuevo, Cerrar sesión

Updating DataTables

Use the following workflow to update a DataTable via CLI:

Run mabl datatables export to get a copy of the DataTable.
Modify the DataTable copy.
Run mabl datatables update to upload the updated version.

For example:

$ mabl datatables export {datatable-id} --fmt csv

# Modify the exported DataTable

$ mabl datatables update {datatable-id} {path-to-file} --fmt csv

Rules for editing

When modifying an exported DataTable, keep the following rules in mind:

Every scenario must have the same variables. All scenarios must list the same variable names, in the same order. You cannot add or remove a variable from just one scenario — the change must apply to all of them.
Variable names must be valid identifiers. They must start with a letter or underscore and contain only letters, numbers, and underscores. The names user, web, and mail are reserved and cannot be used.
Scenario IDs control what happens on upload. The CLI uses scenario IDs to determine which scenarios to create, update, or delete:
- Scenarios with an existing ID are updated.
- Scenarios with no ID (omitted in JSON, or an empty Scenario ID cell in CSV) are created as new.
- Scenarios that existed in the original DataTable but are missing from your file are deleted.
There is no undo for deletions. If you remove a scenario from the file and upload, it is deleted immediately. There is no confirmation prompt or rollback.

Sample file input

File input must be either JSON or CSV. In the following examples, the Spanish scenario has an updated greeting value and a new French scenario has been added.

JSON

[
    {
      "id": "iOdx6S4kwCdhmQspP9m1dw-vr",
      "name": "English",
      "variables": [
        {
          "name": "login",
          "value": "Login"
        },
        {
          "name": "greeting",
          "value": "Welcome back"
        },
        {
          "name": "logout",
          "value": "Logout"
        }
      ]
    },
    {
      "id": "uEb1EkFEeqHyV5TXctUCRw-vr",
      "name": "Spanish",
      "variables": [
        {
          "name": "login",
          "value": "Iniciar sesión"
        },
        {
          "name": "greeting",
          "value": "Bienvenido de nuevo"
        },
        {
          "name": "logout",
          "value": "Cerrar sesión"
        }
      ]
    },
    {
      "name": "French",
      "variables": [
        {
          "name": "login",
          "value": "Connexion"
        },
        {
          "name": "greeting",
          "value": "Content de vous revoir"
        },
        {
          "name": "logout",
          "value": "Déconnexion"
        }
      ]
    }
  ]

CSV

Scenario ID,Scenario name,login,greeting,logout
iOdx6S4kwCdhmQspP9m1dw-vr,English,Login,Welcome back,Logout
uEb1EkFEeqHyV5TXctUCRw-vr,Spanish,Iniciar sesión,Bienvenido de nuevo,Cerrar sesión
,French,Connexion,Content de vous revoir,Déconnexion

Note: Protected DataTables

If a user tries to update or export DataTables belonging to resource groups that they don’t have access to, the mabl CLI returns a 403: Missing permission error.