read_file

Use read_file to inspect an existing model, run.py, README, or data seed before making changes. Do not use it for directory discovery; call list_files first.

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model.')]	Yes	—
path	`Annotated[str	None, Field(description=“Model-relative file path to read (e.g. ‘run.py’, ‘model/revenue.py’). Pass either path for single-file mode or paths for bounded plural mode.”)]`	No	None
paths	`Annotated[list[str]	None, Field(min_length=1, max_length=20, description=‘One to 20 model-relative paths to read at one pinned commit. Each path returns its own success or error entry.’)]`	No	None
encoding	Annotated[Literal['auto', 'text', 'base64'], Field(description="How to decode the file: 'auto' (default) sniffs binary vs text; 'text' returns UTF-8 string; 'base64' returns base64-encoded bytes.")]	No	'auto'
branch	`Annotated[str	None, Field(description=“Branch to operate on. Defaults to the model’s default branch when omitted or null.”)]`	No	None
start_line	Annotated[int, Field(ge=1, description='1-based first line to return for UTF-8 text reads.')]	No	1
line_limit	`Annotated[int	None, Field(ge=1, description=‘Maximum number of complete text lines to return. Omit to read through EOF. Line windows are not available for binary/base64 content.’)]`	No	None
expected_sha	Annotated[str, Field(description='Optional blob SHA returned by a previous read window. If the file changed, the continuation read fails instead of mixing content from different versions.')]	No	''
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• path (string)
• model (string)
• content (string)
• encoding (string)
• sha (string)
• size_bytes (integer)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "read_file",
  "arguments": {
    "model_name": "forecasts",
    "path": "model/revenue.py"
  }
}

Response

{
  "path": "model/revenue.py",
  "model": "forecasts",
  "content": "def run(inputs):\n    ...\n",
  "encoding": "text",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "size_bytes": 482
}

Notes

• Module: Files
• Requires an authenticated Bridge Town session (OAuth) or an API token.