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
@personal
@shared
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
Dataset stored in @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
nbytes: 7.81 KiB
cbytes: 4.90 KiB
ratio : 1.59x
mtime : 2025-10-08T11:09:03.955154Z
cparams:
codec : ZSTD (5)
clevel : 1
filters: [SHUFFLE]
As you see, this command returns digested information of the dataset’s metadata.
You can also see the contents of the dataset:
cat2-client --username user@example.com --password foobar11 show @personal/ds-1d.b2nd
When the dataset is small, the contents are printed to the screen, otherwise a pager is used.
If you want to use a browser to view the contents of the dataset:
cat2-client --username user@example.com --password foobar11 browse @personal/ds-1d.b2nd
Although you will need to authenticate with the server first; after that, this command will open a new tab in your default browser with the contents of the dataset.
There are more commands available in the cat2-client client; ask for help with:
cat2-client --help