Folders

Method	Description
list_folders	List folders at the project root or below parent.
get_folder	Return a folder by ID, or None when it does not exist.
get_folder_by_name	Find a folder by name across the project or below parent.
create_folder	Create and return a folder at the project root or below parent.
folder_tree	Render the full project folder tree or the tree below root.
folder_tree_nodes	Return typed tree nodes for the project forest or below root.
folder_tree_dict	Return structured tree data for the project forest or below root.

list_folders

list_folders(
    *,
    recursive: bool = False,
    name: str | None = None,
    parent: Folder | str | None = None
) -> list[Folder]

List folders at the project root or below parent.

When parent is omitted, returns root folders, or all folders when recursive=True. When a parent Folder is already known, parent.children() or parent.descendants() is usually more ergonomic.

get_folder

get_folder(folder_id: str) -> Folder | None

Return a folder by ID, or None when it does not exist.

get_folder_by_name

get_folder_by_name(
    name: str,
    *,
    exact_match_only: bool = False,
    recursive: bool = True,
    parent: Folder | str | None = None
) -> Folder | None

Find a folder by name across the project or below parent.

Raises AmbiguousFolderError when multiple folders match. This is equivalent to parent.find_child() when the parent is already a resolved folder.

create_folder

create_folder(
    name: str, *, parent: Folder | str | None = None
) -> Folder

Create and return a folder at the project root or below parent.

This is equivalent to parent.create_child(name) when the parent is already a resolved folder.

folder_tree

folder_tree(
    *,
    root: Folder | str | None = None,
    include_root: bool = True,
    max_depth: int | None = None,
    include_project_items: bool = True,
    project_items_limit_per_folder: int | None = 20,
    return_as_str: bool = False
) -> str | None

Render the full project folder tree or the tree below root.

When root is omitted, the render includes unfiled project items. This is equivalent to folder.tree() when the root is already a resolved folder. Prints to the active output by default; set return_as_str=True to receive the rendered tree instead.

folder_tree_nodes

folder_tree_nodes(
    *,
    root: Folder | str | None = None,
    include_root: bool = True,
    max_depth: int | None = None,
    include_project_items: bool = True,
    project_items_limit_per_folder: int | None = 100
) -> FolderTreeNode | list[FolderTreeNode]

Return typed tree nodes for the project forest or below root.

This is equivalent to folder.tree_nodes() when the root is already a resolved folder.

folder_tree_dict

folder_tree_dict(
    *,
    root: Folder | str | None = None,
    include_root: bool = True,
    max_depth: int | None = None,
    include_project_items: bool = True,
    project_items_limit_per_folder: int | None = 100
) -> dict[str, Any] | list[dict[str, Any]]

Return structured tree data for the project forest or below root.

This is equivalent to folder.tree_dict() when the root is already a resolved folder.