Using the command-line client#

For quick queries to a server or for use in shell scripts, Caterva2 ships the cat2-client program. To use it, you need to install Caterva2 with the clients extra, as well as server in order to be able to query something.

python -m pip install caterva2[clients,server]

To create a user, you can use the cat2-admin adduser command. For example:

cat2-admin adduser user@example.com foobar11

Now that the services are running, we can use the cat2-client client to talk to the server. In another shell, let’s list all the available roots in the system:

cat2-client --user "user@example.com" --pass "foobar11" roots

@public (subscribed)
@personal (subscribed)
@shared (subscribed)

First let’s upload a file from the root-examplefolder to the @personal root:

cat2-client --username user@example.com --password foobar11 upload root-example/ds-1d.b2nd @personal/ds-1d.b2nd

Now, one can list the datasets in the @personal root and see that the uploaded file appears

cat2-client --username user@example.com --password foobar11 list @personal
>> ds-1d.b2nd

Let’s ask the server for more info about the dataset:

cat2-client --username user@example.com --password foobar11 info @personal/ds-1d.b2nd

Getting info for @personal/ds-1d.b2nd
{
    'shape': [1000],
    'chunks': [100],
    'blocks': [10],
    'dtype': 'int64',
    'schunk': {
        'cbytes': 5022,
        'chunkshape': 100,
        'chunksize': 800,
        'contiguous': True,
        'cparams': {'codec': 5, 'codec_meta': 0, 'clevel': 1, 'filters': [0, 0, 0, 0, 0, 1], 'filters_meta': [0, 0, 0, 0, 0, 0], 'typesize': 8, 'blocksize': 80, 'nthreads': 1, 'splitmode': 1, 'tuner': 0, 'use_dict': False, 'filters, meta': [[1, 0]]},
        'cratio': 1.5929908403026682,
        'nbytes': 8000,
        'urlpath': '/home/lshaw/Caterva2/_caterva2/sub/personal/2fa87091-84c6-44f9-a57e-7f04290630b1/ds-1d.b2nd',
        'vlmeta': {},
        'nchunks': 10,
        'mtime': None
    },
    'mtime': '2025-05-29T09:11:26.860956Z'
}

This command returns a JSON object with the dataset’s metadata, including its shape, chunks, blocks, data type, and compression parameters. The schunk field contains information about the underlying Blosc2 super-chunk that stores the dataset’s data.

There are more commands available in the cat2-client client; ask for help with:

cat2-client --help

Using the command-line client#

This Page