hfsapi

English | 中文

Python API client for HFS (HTTP File Server): login, file listing, upload, config, and permissions.

Install

Global CLI (recommended) — install so the hfs command is available everywhere:

uv tool install hfsapi
# or (system / user level)
pip install hfsapi

As a project dependency (e.g. for import hfsapi in your code):

pip install hfsapi
# or in a uv-managed project
uv add hfsapi

From source:

uv sync
# or
pip install -e .

Quick start

from hfsapi import HFSClient, entry_size, entry_created, entry_modified

with HFSClient("http://127.0.0.1:8280", username="abct", password="abc123") as client:
    data = client.get_file_list(uri="/data")
    for e in data.get("list", []):
        print(e["n"], entry_size(e), entry_created(e), entry_modified(e))

    # Create folder (same as “New folder” in the web UI)
    client.create_folder("data", "myfolder")

    # Upload
    client.upload_file("data", b"content", filename="hello.txt", use_put=True)

CLI

After installing (e.g. uv tool install hfsapi or pip install hfsapi), the hfs command is available. Log in once to save credentials locally; all other commands then use them (or pass --base-url if not logged in).

hfs login --base-url http://127.0.0.1:8280 -u abct -p abc123
hfs list /data
hfs upload ./local.txt --folder data
hfs upload ./mydir --folder data   # folder: upload contents into --folder (rclone-style)
hfs upload ./file.txt -f data -u -p   # -u print link after upload (resolves server-renamed name), -p progress
hfs mkdir data/myfolder
hfs download data/foo.txt -o ./foo.txt
hfs delete data/foo.txt
hfs config get
hfs vfs
hfs info
hfs logout

Path or URL: For list, upload --folder, download, mkdir, and delete, you can pass either a path (e.g. data/foo.txt) or a full URL (e.g. http://127.0.0.1:8280/data/foo.txt). A URL is parsed to use that server and path for that command.

See hfs --help and hfs <command> --help for options.

Core API

In list responses: n = name, s = size, c/m = created/modified time; can_archive, can_upload, can_delete, etc. indicate the current user’s permissions for that directory.

More details (permission mapping, testing, publishing, upload options and roots) in HELP.md.

Legal: DISCLAIMER.md — no warranty, no liability, use at your own risk.