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

To start the server use the following command:

CATERVA2_SECRET=c2sikrit cat2-server &

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 generate a file and save it locally. Run the following script in the terminal to save a b2nd file to your current directory.

python -c "import blosc2; blosc2.arange(0, 1000, 1, blocks = (10,), chunks=(100,), urlpath='ds-1d.b2nd')"

Let’s upload the file to the @personal root:

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

Dataset stored in @personal/ds-1d.b2nd

Now, one may 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: 3.86 KiB
ratio : 2.02x
mtime : 2025-10-30T11:16:17.012415Z
cparams:
  codec  : ZSTD (5)
  clevel : 5
  filters: [SHUFFLE]

As you see, this command returns digested information of the dataset’s metadata.

You can also see the contents of the dataset from the terminal.

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 you can do that too. First authenticate yourself via the browser window accessible via the url associated with your server instance (probably something like http://localhost:8000). Then run the following command in the terminal to visualise the dataset directly.

cat2-client browse @personal/ds-1d.b2nd

You do 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