---
type: Reference
title: ScalarDL Client Command Reference
description: This page introduces scalardl, which is a client command for interacting with ScalarDL components.
resource: https://scalardl.scalar-labs.com/docs/latest/scalardl-command-reference/
tags:
- scalardl
- v3.14
- phase:implement
- edition:community
- edition:enterprise
status: stable
product: scalardl
product_title: ScalarDL
version: '3.14'
patch_version: 3.14.0
doc_id: scalardl-command-reference
lifecycle_phase: implement
editions:
- Community
- Enterprise
generated:
  by: process:okf-build/1.0.0
  at: '2026-08-10T20:40:01Z'
sources:
- id: docs-scalardl
  resource: https://github.com/scalar-labs/docs-scalardl/blob/03da04b21c1a7ce3eb94d9e29129a0ce194ecbeb/docs/scalardl-command-reference.mdx
  title: ScalarDL documentation source (MDX)
  author: process:scalar-labs/docs-scalardl
  last_modified: '2026-08-07T17:27:19Z'
---

# ScalarDL Client Command Reference

This page introduces `scalardl`, which is a client command for interacting with ScalarDL components.

## Overview of commands

- **Bootstrap a client**
  - [`bootstrap`](#bootstrap): Bootstrap a client by registering the identity information and system contracts.
- **Register identity information**
  - [`register-cert`](#register-cert): Register a specified certificate.
  - [`register-secret`](#register-secret): Register a specified secret.
- **Register business logic**
  - [`register-contract`](#register-contract): Register a specified contract.
  - [`register-contracts`](#register-contracts): Register specified contracts.
  - [`register-function`](#register-function): Register a specified function.
  - [`register-functions`](#register-functions): Register specified functions.
- **Execute and list the registered business logic**
  - [`execute-contract`](#execute-contract): Execute a specified contract.
  - [`list-contracts`](#list-contracts): List registered contracts.
- **Manage namespaces**
  - [`create-namespace`](#create-namespace): Create a namespace.
  - [`list-namespaces`](#list-namespaces): List namespaces.
  - [`drop-namespace`](#drop-namespace): Drop a namespace.
- **Manage transaction state**
  - [`purge-state`](#purge-state): Purge residual transaction state that ScalarDL retains.
- **Validate a ledger**
  - [`validate-ledger`](#validate-ledger): Validate a specified asset in a ledger.
- **Run commands for generic-contracts**
  - [`generic-contracts`](#generic-contracts): Run commands for a generic-contracts-based setup.

## `bootstrap`

Bootstrap a client by registering the identity information and system contracts. This command performs the following:

1. Registers a certificate or secret based on the authentication method configured in the properties file.
2. Registers the `ValidateLedger` contract if Auditor is enabled.

If the identity information or the contract is already registered, the command skips the registration and continues without error.

### Options

| Option                     | Description                                |
|:---------------------------|:-------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format. |

[Common utility options](#common-utility-options) are also available.

### Examples

```console
scalardl bootstrap --properties client.properties
```

## `register-cert`

Register a specified certificate.

### Options

| Option                     | Description                                                    |
|:---------------------------|:---------------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.                     |
| `--namespace`              | A namespace where the certificate is registered.               |
| `--entity-id`              | An entity ID for the certificate.                              |
| `--cert-path`              | A path to a PEM-formatted certificate file.                    |
| `--cert-version`           | The version of the certificate (default: 1).                   |

When `--namespace` is specified, `--entity-id` and `--cert-path` are also required. When `--namespace` is not specified, the identity information from the properties file is used.

[Common utility options](#common-utility-options) are also available.

### Examples

Register a certificate by using identity information from the properties file.

```console
scalardl register-cert --properties client.properties
```

Register a certificate to a specific namespace.

```console
scalardl register-cert --properties client.properties --namespace my_namespace --entity-id my_entity --cert-path /path/to/cert.pem
```

## `register-secret`

Register a specified secret.

### Options

| Option                     | Description                                                    |
|:---------------------------|:---------------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.                     |
| `--namespace`              | A namespace where the secret is registered.                    |
| `--entity-id`              | An entity ID for the secret.                                   |
| `--secret-key`             | A secret key for HMAC authentication.                          |
| `--secret-key-version`     | The version of the secret key (default: 1).                    |

When `--namespace` is specified, `--entity-id` and `--secret-key` are also required. When `--namespace` is not specified, the identity information from the properties file is used.

[Common utility options](#common-utility-options) are also available.

### Examples

Register a secret by using identity information from the properties file.

```console
scalardl register-secret --properties client.properties
```

Register a secret to a specific namespace.

```console
scalardl register-secret --properties client.properties --namespace my_namespace --entity-id my_entity --secret-key my-secret-key
```

## `register-contract`

Register a specified contract.

### Options

| Option                     | Description                                                                                    |
|:---------------------------|:-----------------------------------------------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.                                                     |
| `--contract-binary-name`   | A binary name of a contract to register.                                                       |
| `--contract-class-file`    | A contract class file to register.                                                             |
| `--contract-id`            | An ID of a contract to register.                                                               |
| `--contract-properties`    | Contract properties in a serialized format.                                                  |
| `--deserialization-format` | A deserialization format for contract properties. Valid values: JSON or STRING (default: JSON) |

[Common utility options](#common-utility-options) are also available.

### Examples

```console
scalardl register-contract --properties client.properties --contract-id StateUpdater --contract-binary-name com.org1.contract.StateUpdater --contract-class-file build/classes/java/main/com/org1/contract/StateUpdater.class
```

## `register-contracts`

Register specified contracts.

### Options

| Option                     | Description                                            |
|:---------------------------|:-------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.             |
| `--contracts-file`         | A file that includes contracts to register in TOML format. |

[Common utility options](#common-utility-options) are also available.

### Examples

```console
scalardl register-contracts --properties client.properties --contracts-file /path/to/contracts-file
```

An example of the contracts file is as follows.

```toml
[[contracts]]
contract-id = "StateUpdater"
contract-binary-name = "com.org1.contract.StateUpdater"
contract-class-file = "build/classes/java/main/com/org1/contract/StateUpdater.class"

[[contracts]]
contract-id = "StateReader"
contract-binary-name = "com.org1.contract.StateReader"
contract-class-file = "build/classes/java/main/com/org1/contract/StateReader.class"
```

## `register-function`

Register a specified function.

### Options

| Option                     | Description                                                                                    |
|:---------------------------|:-----------------------------------------------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.                                                     |
| `--function-binary-name`   | A binary name of a function to register.                                                       |
| `--function-class-file`    | A function class file to register.                                                             |
| `--function-id`            | An ID of a function to register.                                                               |

[Common utility options](#common-utility-options) are also available.

### Examples

```console
scalardl register-function --properties client.properties --function-id test-function --function-binary-name com.example.function.TestFunction --function-class-file /path/to/TestFunction.class
```

## `register-functions`

Register specified functions.

### Options

| Option                     | Description                                            |
|:---------------------------|:-------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.             |
| `--functions-file`         | A file that includes functions to register in TOML format. |

[Common utility options](#common-utility-options) are also available.

### Examples

```console
scalardl register-functions --properties client.properties --functions-file /path/to/functions-file
```

An example of the functions file is as follows.

```toml
[[functions]]
function-id = "TestFunction1"
function-binary-name = "com.org1.function.TestFunction1"
function-class-file = "build/classes/java/main/com/org1/function/TestFunction1.class"

[[functions]]
function-id = "TestFunction2"
function-binary-name = "com.org1.function.TestFunction2"
function-class-file = "build/classes/java/main/com/org1/function/TestFunction2.class"
```

## `execute-contract`

Execute a specified contract.

### Options

| Option                     | Description                                                                                              |
|:---------------------------|:---------------------------------------------------------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.                                                               |
| `--contract-argument`      | An argument for a contract to execute in a serialized format.                                            |
| `--contract-id`            | An ID of a contract to execute.                                                                          |
| `--deserialization-format` | A deserialization format for contract and function arguments. Valid values: JSON or STRING (default: JSON) |
| `--function-id`            | An ID of a function to execute.                                                                          |

[Common utility options](#common-utility-options) are also available.

### Examples

Execute a contract without a function.

```console
scalardl execute-contract --properties client.properties --contract-id StateUpdater --contract-argument '{"asset_id":"some_asset", "state":3}'
```

Execute a contract with a function.

```console
scalardl execute-contract --properties client.properties --contract-id TestContract --contract-argument '{...}' --function-id TestFunction --function-argument '{...}'
```

## `list-contracts`

List registered contracts.

### Options

| Option                     | Description                                |
|:---------------------------|:-------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format. |
| `--contract-id`            | The ID of a contract to show.               |

[Common utility options](#common-utility-options) are also available.

### Examples

List all contracts registered by the specified entity.

```console
scalardl list-contracts --properties client.properties
```

Show a specified contract only.

```console
scalardl list-contracts --properties client.properties --contract-id StateUpdater
```

## `create-namespace`

:::warning

The namespace feature is currently in Public Preview. The feature and related documentation are subject to change.

:::

Create a namespace. A namespace name must start with an alphabetic character and can only contain alphanumeric characters and underscores (pattern: `[a-zA-Z][a-zA-Z0-9_]*`). The default namespace `default` is reserved and cannot be created or dropped.

### Options

| Option                     | Description                                |
|:---------------------------|:-------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format. |
| `--namespace`              | A name for the namespace that will be created.                |

[Common utility options](#common-utility-options) are also available.

### Examples

```console
scalardl create-namespace --properties client.properties --namespace my_namespace
```

## `list-namespaces`

:::warning

The namespace feature is currently in Public Preview. The feature and related documentation are subject to change.

:::

List namespaces.

### Options

| Option                     | Description                                   |
|:---------------------------|:----------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.    |
| `--pattern`                | A pattern to filter namespaces (partial match). |

[Common utility options](#common-utility-options) are also available.

### Examples

List all namespaces.

```console
scalardl list-namespaces --properties client.properties
```

List namespaces that match a specified pattern.

```console
scalardl list-namespaces --properties client.properties --pattern my_
```

## `drop-namespace`

:::warning

The namespace feature is currently in Public Preview. The feature and related documentation are subject to change.

:::

Drop a namespace. This command requires confirmation by typing the namespace name.

### Options

| Option                     | Description                                |
|:---------------------------|:-------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format. |
| `--namespace`              | The name of the namespace to drop.         |

[Common utility options](#common-utility-options) are also available.

### Examples

```console
scalardl drop-namespace --properties client.properties --namespace my_namespace
```

## `purge-state`

Purge residual transaction state (Coordinator state records and request proofs) that ScalarDL retains for completed transactions. This command is available only when Auditor is enabled and transaction state purge is enabled on both Ledger and Auditor (`scalar.dl.ledger.transaction_state_purge.enabled` and `scalar.dl.auditor.transaction_state_purge.enabled` set to `true`). For more details, see [Purge Residual Transaction State](./purge-residual-transaction-state.md).

By default, this command prompts for confirmation before purging. To skip the prompt (for example, in a non-interactive environment), use the `--force` option.

### Options

| Option                     | Description                                                     |
|:---------------------------|:---------------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.                     |
| `-f`, `--force`            | Purge residual transaction state without prompting for confirmation. |

[Common utility options](#common-utility-options) are also available.

### Examples

Purge residual transaction state. This prompts for confirmation before purging.

```console
scalardl purge-state --properties client.properties
```

Purge residual transaction state without the confirmation prompt.

```console
scalardl purge-state --properties client.properties --force
```

The command returns a summary of how many transactions were targeted, purged, and skipped.

```json
{
  "status_code": "OK",
  "output": {
    "total_targets": 5,
    "purged": 4,
    "skipped": 1
  }
}
```

## `validate-ledger`

Validate a specified asset in a ledger.

### Options

| Option                     | Description                                                                            |
|:---------------------------|:---------------------------------------------------------------------------------------|
| `--config`, `--properties` | A configuration file in properties format.                                             |
| `--namespace`              | The namespace of the asset. If not specified, the `scalar.dl.client.context.namespace` value in the properties file will be used. If that is also not configured, the `default` namespace will be used. |
| `--asset-id`               | The ID of an asset or the ID and the ages of an asset. Format: 'ASSET_ID', the ID of an asset to validate, or 'ASSET_ID,START_AGE,END_AGE', the ID and the ages of an asset to validate. |

[Common utility options](#common-utility-options) are also available.

### Examples

Validate an asset for all ages.

```console
scalardl validate-ledger --properties client.properties --asset-id 'some_asset'
```

Validate an asset from age 0 to age 10 only.

```console
scalardl validate-ledger --properties client.properties --asset-id 'some_asset,0,10'
```

## `generic-contracts`

:::tip

Although generic contracts were introduced in ScalarDL 3.10, HashStore, released in ScalarDL 3.12, provides a higher-level abstraction that wraps generic contracts. For most use cases, using HashStore is simpler and more efficient than using generic contracts directly. For details, see [Get Started with ScalarDL HashStore](./getting-started-hashstore.md) in the latest version of ScalarDL.

:::

Run commands for a generic-contracts-based setup, which are almost the same subcommands for the `scalardl` command. The only difference is in the `validate-ledger` subcommand, where you can specify assets by object IDs of the generic-contracts context instead of the raw asset IDs. For the other subcommands, see each corresponding command in the following [Subcommands](#subcommands) section.

:::tip

You can also use the `scalardl-gc` top-level command and the `gc` subcommand as aliases of the `generic-contracts` subcommand.

:::

### Subcommands

| Subcommand                                                  | Description                             |
|:------------------------------------------------------------|:----------------------------------------|
| [`register-cert`](#register-cert)                           | Register a specified certificate.       |
| [`register-secret`](#register-secret)                       | Register a specified secret.            |
| [`register-contract`](#register-contract)                   | Register a specified contract.          |
| [`register-contracts`](#register-contracts)                 | Register multiple specified contracts.  |
| [`register-function`](#register-function)                   | Register a specified function.          |
| [`register-functions`](#register-functions)                 | Register multiple specified functions.    |
| [`execute-contract`](#execute-contract)                     | Execute a specified contract.           |
| [`list-contracts`](#list-contracts)                         | List the registered contracts.          |
| [`validate-ledger`](#validate-ledger-for-generic-contracts) | Validate a specified asset in a ledger. |

### `validate-ledger` for generic contracts

Validate a specified [asset](./data-modeling.md#asset) in a ledger.

:::note

Generic contracts internally assign a dedicated asset ID to an [asset record](./data-modeling.md#asset-record) that represents an object or collection. The asset ID consists of a prefix for the asset type and keys; for example, a prefix `o_` and an object ID for an object. Therefore, you will see such raw asset IDs after running the `validate-ledger` command.

:::

#### Options

| Option                     | Description                                                          |
|:---------------------------|:---------------------------------------------------------------------|
| `--config`, `--properties` | A configuration file in the .properties format.                      |
| `--object-id`              | The ID of an object created by the `object.Put` contract.            |
| `--collection-id`          | The ID of a collection created by the `collection.Create` contract.  |
| `--start-age`              | The validation start age of the asset (optional).                    |
| `--end-age`                | The validation end age of the asset (optional).                      |

[Common utility options](#common-utility-options) are also available.

### Examples for using subcommands

Register a specified certificate. For available options, see [`register-cert`](#register-cert).

```console
scalardl generic-contracts register-cert --properties client.properties
```

Register a specified secret. For available options, see [`register-secret`](#register-secret).

```console
scalardl generic-contracts register-secret --properties client.properties
```

Register a specified contract. For available options, see [`register-contract`](#register-contract).

```console
scalardl generic-contracts register-contract --properties client.properties --contract-id object.Put --contract-binary-name com.scalar.dl.genericcontracts.object.Put --contract-class-file /path/to/Put.class
```

Register specified contracts. For available options, see [`register-contracts`](#register-contracts).

```console
scalardl generic-contracts register-contracts --properties client.properties --contracts-file /path/to/contracts-file
```

Register a specified function. For available options, see [`register-function`](#register-function).

```console
scalardl generic-contracts register-function --properties client.properties --function-id object.PutToMutableDatabase --function-binary-name com.scalar.dl.genericcontracts.object.PutToMutableDatabase --function-class-file /path/to/PutToMutableDatabase.class
```

Register specified functions. For available options, see [`register-functions`](#register-functions).

```console
scalardl generic-contracts register-functions --properties client.properties --functions-file /path/to/functions-file
```

Execute a specified contract. For available options, see [`execute-contract`](#execute-contract).

```console
scalardl generic-contracts execute-contract --properties client.properties --contract-id object.Put --contract-argument '{"object_id": "a.txt", "hash_value": "b97a42c87a46ffebe1439f8c1cd2f86e2f9b84dad89c8e9ebb257a19b6fdfe1c", "metadata": {"note": "updated"}}'
```

List registered contracts. For available options, see [`list-contracts`](#list-contracts).

```console
scalardl generic-contracts list-contracts --properties client.properties
```

Validate an object for all ages.

```console
scalardl generic-contracts validate-ledger --properties client.properties --object-id 'a.txt'
```

Validate an object from age 0 to age 10 only.

```console
scalardl generic-contracts validate-ledger --properties client.properties --object-id 'a.txt' --start-age 0 --end-age 10
```

Validate a collection for all ages.

```console
scalardl generic-contracts validate-ledger --properties client.properties --collection-id 'audit_set'
```

Use the top-level command `scalardl-gc` as the alias of `scalardl generic-contracts`.

```console
scalardl-gc validate-ledger --properties client.properties --object-id 'a.txt'
```

Use the subcommand `scalardl gc` as the alias of `scalardl generic-contracts`.

```console
scalardl gc validate-ledger --properties client.properties --object-id 'a.txt'
```

## Common utility options

You can use the following options in all the commands above.

| Option                | Description                                 |
|:----------------------|:--------------------------------------------|
| `-g`, `--use-gateway` | A flag to use the gateway.                  |
| `-h`, `--help`        | Display the help message of a command.      |
| `--stacktrace`        | Output Java Stack Trace to `stderr` stream. |
