gfal-cli

A Python reimplementation of the gfal2-util command-line tools, built on fsspec. Supports local files, HTTP/HTTPS, and XRootD (root://).

Installation

From PyPI

pip install gfal-cli

From Native Repository (Recommended for Updates)

Enable the repository to receive automatic updates via dnf update or apt upgrade.

YUM (AlmaLinux / RHEL)

sudo curl -sL -o /etc/yum.repos.d/gfal-cli.repo https://lobis.github.io/gfal-cli/rpm/gfal-cli.repo
sudo dnf install -y python3-gfal-cli

APT (Ubuntu / Debian)

Add the repository:

echo "deb [trusted=yes] https://lobis.github.io/gfal-cli/deb/ stable main" | sudo tee /etc/apt/sources.list.d/gfal-cli.list
sudo apt-get update
sudo apt-get install -y python3-gfal-cli

After installation the following commands are available on your PATH:

Quick start

All commands accept any URL that fsspec understands. Local paths must be given as file:// URIs.

# Stat a local file
gfal-stat file:///tmp/test.txt

# List a remote HTTP directory
gfal-ls https://example.com/data/

# Copy a file from XRootD to local
gfal-cp root://eosuser.cern.ch//eos/user/j/jdoe/file.root file:///tmp/file.root

# Copy with checksum verification
gfal-cp -K ADLER32 root://server//path/src.dat file:///tmp/dst.dat

# Recursive copy
gfal-cp -r root://server//path/srcdir/ file:///tmp/dstdir/

# Remove a directory tree
gfal-rm -r file:///tmp/old_dir/

# Compute a checksum
gfal-sum file:///tmp/file.root ADLER32

Command reference

gfal-ls

gfal-ls [OPTIONS] URI [URI ...]

gfal-ls -lH root://server//eos/data/
gfal-ls -la file:///tmp/mydir/
gfal-ls -l --time-style=full-iso https://example.com/files/

gfal-cp / gfal-copy

gfal-cp [OPTIONS] SRC [SRC ...] DST

# Simple copy
gfal-cp file:///tmp/src.txt https://server/dst.txt

# Force overwrite with ADLER32 verification
gfal-cp -f -K ADLER32 root://server//path/file.root file:///tmp/file.root

# Recursive copy, create parents
gfal-cp -r -p root://server//eos/srcdir/ file:///tmp/dstdir/

# Third-party copy between two XRootD servers
gfal-cp --tpc root://src-server//path/file root://dst-server//path/file

gfal-rm

gfal-rm [OPTIONS] URI [URI ...]

gfal-rm file:///tmp/old.txt
gfal-rm -r root://server//eos/old_dir/
gfal-rm --dry-run root://server//eos/dir/     # preview only

gfal-stat

gfal-stat URI [URI ...]

Prints POSIX-style stat information (size, permissions, timestamps):

  File: 'root://server//eos/data/file.root'
  Size: 1048576        regular file
Access: (0644/-rw-r--r--)      Uid: 1000   Gid: 1000
Access: 2025-06-01 12:34:56.000000
Modify: 2025-06-01 12:34:56.000000
Change: 2025-06-01 12:34:56.000000

gfal-mkdir

gfal-mkdir [OPTIONS] URI [URI ...]

gfal-mkdir root://server//eos/user/j/jdoe/newdir
gfal-mkdir -p root://server//eos/user/j/jdoe/a/b/c

gfal-sum

gfal-sum URI ALGORITHM

Supported algorithms: ADLER32, CRC32, CRC32C, MD5, SHA1, SHA256, SHA512.

gfal-sum file:///tmp/file.root ADLER32
# file:///tmp/file.root 0a1b2c3d

gfal-cat

gfal-cat URI [URI ...]

Prints file contents to stdout. Multiple files are concatenated.

gfal-save

gfal-save URI

Reads from stdin and writes to the given URI.

echo "hello" | gfal-save root://server//eos/user/j/jdoe/hello.txt

gfal-rename

gfal-rename SOURCE DESTINATION

gfal-chmod

gfal-chmod MODE URI [URI ...]

MODE is an octal permission string, e.g. 0644 or 755.

Common options

Every command accepts these global flags:

Authentication

X.509 proxy (XRootD / HTTPS): If X509_USER_PROXY is set or a proxy exists at /tmp/x509up_u<uid>, it is used automatically. Override with -E/--key.

HTTPS client certificates: Pass --cert and --key for mutual TLS authentication.

Development

git clone https://github.com/lobis/gfal-cli.git
cd gfal-cli

python -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"
pytest tests/