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

This Page