update_file

Overwrite an existing file in a Bridge Town project and commit the change. The path is project-relative (e.g. ‘README.md’, ‘model/revenue.py’, ‘data/seed.csv’, ‘assets/logo.png’). This tool is strict update-only: if the file does not exist it returns a not-found error instructing you to use create_file instead. Specify branch to commit to 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. encoding must be ‘text’ for UTF-8 source files or ‘base64’ for binary files; encoding=‘auto’ is not allowed on writes. Pass expected_sha (the sha returned by read_file or a prior write tool) to enable optimistic concurrency control: if another session modified the file since you last read it the tool raises a ToolError with a structured conflict payload so you can merge and retry without an extra read_file call. If commit_message is omitted the server generates a default of the form ‘feat: update {filename} (Bridge Town)’. Supply a descriptive commit_message for clearer project history. Requires at least Editor access to the project. Returns: path (str) — updated file path; project (str) — project name; commit_sha (str) — git commit SHA of the change. On conflict: error (str) — ‘commit-conflict’; message (str) — human-readable description; hint (str) — suggested retry action; current_sha (str) — actual current blob SHA; current_content (str) — current file content (text or base64, merge changes here); your_sha (str) — the expected_sha you supplied.

Parameters

Name	Type	Required	Default	Description
project_name	str	Yes	—
path	str	Yes	—
content	str	Yes	—
encoding	str	No	'text'
commit_message	str	No	''
branch	`str	None`	No	None
expected_sha	str	No	''

Returns

Returns a structured object. Top-level fields:

• path (string)
• project (string)
• commit_sha (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "update_file",
  "arguments": {
    "project_name": "forecasts",
    "path": "model/revenue.py",
    "content": "def run(inputs):\n    return {\"revenue\": 1000}\n",
    "commit_message": "refactor: simplify revenue model",
    "expected_sha": "0123456789abcdef0123456789abcdef01234567"
  }
}

Response

{
  "path": "model/revenue.py",
  "project": "forecasts",
  "commit_sha": "abc1234def5678901234567890abcdef12345678"
}

Notes

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