list_files

List files and directories in a Bridge Town project (or a subtree). Returns file names, paths, sizes, and types for entries under the given path. Use path=” to list from the project root. Useful for discovering stale files (e.g. a leftover run.py inside model/) that auto-discovery would accidentally execute. Specify branch to inspect a non-default branch (e.g. a scenario branch). Omitting branch, passing an empty string, or passing null all resolve to the project’s default branch. Passing the branch name explicitly is equivalent. Use max_results to bound the response size (default 100, max 1000). When the result is truncated, the response includes truncated=true and total_count so you know how many matching entries exist in total. Use pattern for server-side glob filtering against the project-relative path of each entry (e.g. ‘.py’ returns only Python files, ‘model/.py’ returns only Python files directly inside model/, ’**/.yaml’ returns all YAML files at any depth). Filtering happens before max_results is applied. pattern=‘model/.py’ is the recommended replacement for the retired list_models tool. Returns: project (str) — project name; path (str) — root path that was queried; branch (str|null) — branch ref used (null = default branch); files (list[{name, path, size, type}]) — entries where type is ‘file’, ‘dir’, or ‘symlink’; count (int) — number of entries returned; total_count (int) — total matching entries before max_results cap; truncated (bool) — true when results were capped by max_results or the traversal hard cap.

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
project_name	str	Yes	—
path	str	No	''
branch	`str	None`	No	None
max_results	int	No	100
pattern	str	No	''

Returns

Returns a structured object. Top-level fields:

• project (string)
• path (string)
• branch (null)
• files (array<object>)
• count (integer)
• total_count (integer)
• truncated (boolean)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "list_files",
  "arguments": {
    "project_name": "forecasts",
    "path": "model",
    "pattern": "*.py",
    "max_results": 50
  }
}

Response

{
  "project": "forecasts",
  "path": "model",
  "branch": null,
  "files": [
    {
      "name": "revenue.py",
      "path": "model/revenue.py",
      "size": 482,
      "type": "file"
    },
    {
      "name": "headcount.py",
      "path": "model/headcount.py",
      "size": 612,
      "type": "file"
    }
  ],
  "count": 2,
  "total_count": 2,
  "truncated": false
}

Notes

• Module: Models
• Requires authentication via API token or Auth0 JWT.