Filesharing Service List Files Task

task api name: list_files

The list_files task lists the immediate files and subdirectories under a File Sharing URL. It does not descend into nested directories.

Inputs

Parameter	Required	Description
url	No	Directory URL to list, default nf://

Output

Returns directory entries for the requested nf:// URL. Results are worker keyed when called through client.run_job(...).

Examples

CLIPython

List the repository root:

nf#file list url nf://

List a subdirectory:

nf#file list url nf://templates/

Context manager:

from norfab.core.nfapi import NorFab

with NorFab(inventory="./inventory.yaml") as nf:
    client = nf.make_client()

    result = client.run_job(
        service="filesharing",
        task="list_files",
        workers="any",
        kwargs={"url": "nf://"},
    )
    print(result)

Direct lifecycle:

from norfab.core.nfapi import NorFab

nf = NorFab(inventory="./inventory.yaml")
try:
    nf.start()
    client = nf.make_client()

    result = client.run_job(
        service="filesharing",
        task="list_files",
        workers="any",
        kwargs={"url": "nf://templates/"},
    )
    print(result)
finally:
    nf.destroy()

Filesharing List Files Command Shell Reference

NorFab shell supports these command options for Filesharing list_files task:

nf# man tree file.list
root
└── file:    File sharing service
    └── list:    List files
        └── url:    Directory to list content for, default 'nf://'

nf#

Python API Reference

List files in a directory.

Parameters:

Name	Type	Description	Default
url	str	URL path starting with 'nf://' to list files from	required

Returns:

Type	Description
Result	Result containing list of files or error message

Source code in norfab\workers\filesharing_worker\filesharing_worker.py

@Task(
    input=ListFilesInput,
    output=ListFilesResult,
    fastapi={"methods": ["GET"]},
    agent={"enabled": False},
    mcp={
        "annotations": {
            "title": "List Files",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": False,
        }
    },
)
def list_files(self, url: str) -> Result:
    """
    List files in a directory.

    Args:
        url: URL path starting with 'nf://' to list files from

    Returns:
        Result containing list of files or error message
    """
    ret = Result(result=None)
    try:
        full_path = self._safe_path(url)
    except ValueError as e:
        ret.failed = True
        ret.errors = [str(e)]
        return ret

    if os.path.exists(full_path) and os.path.isdir(full_path):
        ret.result = os.listdir(full_path)
    else:
        ret.errors = ["Directory Not Found"]
        ret.failed = True
    return ret