---
type: Documentation Page
title: ScalarDB Analytics CLI Command Reference
description: 'The ScalarDB Analytics CLI uses a hierarchical command structure:'
resource: https://scalardb.scalar-labs.com/docs/latest/scalardb-analytics/reference-cli-command/
tags:
- scalardb
- v3.19
- phase:implement
- edition:enterprise-option
status: stable
product: scalardb
product_title: ScalarDB
version: '3.19'
patch_version: 3.19.0
doc_id: scalardb-analytics/reference-cli-command
lifecycle_phase: implement
editions:
- Enterprise Option
generated:
  by: process:okf-build/1.0.0
  at: '2026-08-10T20:39:58Z'
sources:
- id: docs-scalardb
  resource: https://github.com/scalar-labs/docs-scalardb/blob/8bb9295f8fbd8a042360ebb5a3e70f8c4e5dfa47/docs/scalardb-analytics/reference-cli-command.mdx
  title: ScalarDB documentation source (MDX)
  author: process:scalar-labs/docs-scalardb
  last_modified: '2026-08-07T16:37:01Z'
---

# ScalarDB Analytics CLI Command Reference

The ScalarDB Analytics CLI uses a hierarchical command structure:

```
scalardb-analytics-cli <resource> <operation> [options]
```

Available resources:

- **catalog:** Top-level containers for organizing data sources
- **data-source:** External databases registered within catalogs
- **namespace:** Database-specific organizational units
- **table:** Database tables within namespaces

## Catalog operations

This section describes how to create a new catalog, list all catalogs, show catalog details, and delete a catalog.

### Create a new catalog

Creating a new catalog can be done as follows. Please replace `<catalog-name>` with the name of a catalog you create.

```
scalardb-analytics-cli catalog create --catalog <catalog-name>
```

### List all catalogs

Display all existing catalogs in the system.

```
scalardb-analytics-cli catalog list
```

### Show catalog details

Display detailed information about a specific catalog. You can specify the catalog either by its name or by its UUID.

To specify by catalog name:
```
scalardb-analytics-cli catalog describe --catalog <catalog-name>
```

Please replace `<catalog-name>` with the name of the catalog you want to describe.

To specify by catalog ID:
```
scalardb-analytics-cli catalog describe --catalog-id <catalog-uuid>
```

Please replace `<catalog-uuid>` with the UUID of the catalog you want to describe.

### Delete a catalog

Remove a catalog from the system. The operation fails if the catalog contains data sources unless you use the `--cascade` option to delete all contents.

You can specify the catalog either by its name or by its UUID.

To delete an empty catalog by name:

```
scalardb-analytics-cli catalog delete --catalog <catalog-name>
```

Please replace `<catalog-name>` with the name of the catalog you want to delete.

To delete a catalog by ID:

```
scalardb-analytics-cli catalog delete --catalog-id <catalog-uuid>
```

Please replace `<catalog-uuid>` with the UUID of the catalog you want to delete.

To delete a catalog and all its contents (data sources and their children):

```
scalardb-analytics-cli catalog delete --catalog <catalog-name> --cascade
```

## Data source operations

This section describes how to register a new data source, list all data sources, show data source details, and delete a data source.

### Register a new data source

Add a new data source to a catalog by specifying the catalog name, data source name, and provider configuration.

```
scalardb-analytics-cli data-source register --catalog <catalog-name> --data-source <data-source-name> <provider-option> [schema-option]
```

Please replace:

- `<catalog-name>` with the name of the catalog that will own the data source.
- `<data-source-name>` with the name of the data source to register.

#### Provider options

You must specify the provider configuration by using one of the following options:

- `--provider-json <json>`: Inline JSON payload that describes the data source provider.
- `--provider-file <path>`: Path to a JSON file that describes the data source provider.
- `--provider-stdin`: Read the provider JSON payload from standard input.

#### Schema options

For the providers that do not support automatic schema resolution, such as DynamoDB, you must manually specify the schema definition by using one of the following methods:

- `--schema-json <json>`: Inline JSON payload that describes the data source schema.
- `--schema-file <path>`: Path to a JSON file that describes the data source schema.

:::note

Whether a schema is required depends on the provider type. Some providers, such as PostgreSQL and MySQL, resolve schemas automatically and do not accept manual schema input. Other providers, such as DynamoDB, require a schema to be provided through one of the available schema options.

:::

#### Examples

To register a data source by using a provider file:

```
scalardb-analytics-cli data-source register --catalog my_catalog --data-source my_datasource --provider-file /path/to/provider.json
```

Please replace `/path/to/provider.json` with the path to the provider file.

To register a data source by using inline JSON:

```
scalardb-analytics-cli data-source register --catalog my_catalog --data-source my_datasource --provider-json '{"type":"postgresql","host":"localhost","port":5432,"database":"mydb","user":"user","password":"pass"}'
```

To register a data source by using standard input:

```
cat provider.json | scalardb-analytics-cli data-source register --catalog my_catalog --data-source my_datasource --provider-stdin
```

The provider JSON format is described in the [Data Source Reference](./reference-data-source.md).

### List all data sources

Display all data sources within a specific catalog.

```
scalardb-analytics-cli data-source list --catalog <catalog-name>
```

Please replace `<catalog-name>` with the name of the catalog whose data sources you want to list.

### Show data source details

Display detailed information about a specific data source. You can specify the data source either by its name within a catalog or by its UUID.

To specify by catalog and data source name:

```
scalardb-analytics-cli data-source describe --catalog <catalog-name> --data-source <data-source-name>
```

Please replace:
- `<catalog-name>` with the name of the catalog containing the data source
- `<data-source-name>` with the name of the data source you want to describe

To specify by data source ID:

```
scalardb-analytics-cli data-source describe --data-source-id <data-source-uuid>
```

Please replace `<data-source-uuid>` with the UUID of the data source you want to describe.

### Delete a data source

Remove a data source from a catalog. The operation fails if the data source contains namespaces unless you use the `--cascade` option to delete all contents.

You can specify the data source either by its name within a catalog or by its UUID.

To delete an empty data source by name:

```
scalardb-analytics-cli data-source delete --catalog <catalog-name> --data-source <data-source-name>
```

Please replace:
- `<catalog-name>` with the name of the catalog containing the data source
- `<data-source-name>` with the name of the data source you want to delete

To delete a data source by ID:

```
scalardb-analytics-cli data-source delete --data-source-id <data-source-uuid>
```

Please replace `<data-source-uuid>` with the UUID of the data source you want to delete.

To delete a data source and all its contents (namespaces, tables, and columns):

```
scalardb-analytics-cli data-source delete --catalog <catalog-name> --data-source <data-source-name> --cascade
```

## Namespace operations

This section describes how to list all namespaces and show namespace details.

### List all namespaces

Display all namespaces within a specific catalog.

```
scalardb-analytics-cli namespace list --catalog <catalog-name>
```

Please replace:
- `<catalog-name>` with the name of the catalog whose namespaces you want to list

### Show namespace details

Display detailed information about a specific namespace. You can specify the namespace either by its name within a data source or by its UUID. For nested namespaces, use `.` as a separator (for example, `--namespace parent.child`).

To specify by catalog, data source, and namespace name:

```
scalardb-analytics-cli namespace describe --catalog <catalog-name> --data-source <data-source-name> --namespace <namespace-name>
```

Please replace:
- `<catalog-name>` with the name of the catalog containing the data source
- `<data-source-name>` with the name of the data source containing the namespace
- `<namespace-name>` with the name of the namespace you want to describe

To specify by namespace ID:

```
scalardb-analytics-cli namespace describe --namespace-id <namespace-uuid>
```

Please replace `<namespace-uuid>` with the UUID of the namespace you want to describe.

## Table operations

This section describes how to list all tables and show the table schema.

### List all tables

Display all tables within a specific catalog.

```
scalardb-analytics-cli table list --catalog <catalog-name>
```

Please replace:
- `<catalog-name>` with the name of the catalog containing the data source

### Show the table schema

Display the schema information including all columns for a specific table. You can specify the table either by its name within a namespace or by its UUID. For nested namespaces, use `.` as a separator (for example, `--namespace parent.child`).

To specify by catalog, data source, namespace, and table name:
```
scalardb-analytics-cli table describe --catalog <catalog-name> --data-source <data-source-name> --namespace <namespace-name> --table <table-name>
```

Please replace:
- `<catalog-name>` with the name of the catalog containing the data source
- `<data-source-name>` with the name of the data source containing the namespace
- `<namespace-name>` with the name of the namespace containing the table
- `<table-name>` with the name of the table you want to describe

To specify by table ID:
```
scalardb-analytics-cli table describe --table-id <table-uuid>
```

Please replace `<table-uuid>` with the UUID of the table you want to describe.
