File and Shell Tools

Four tools cover file content over the API: read, write, edit and bash. Paths are workspace-absolute (/Projects/auth.py), Monofile versions every write, and the writes of one call land in one changeset. The request envelope is the same for all of them, see Calling Tools.

curl -X POST "https://www.monofile.ai/api/tools/read" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Projects/auth.py", "includeMetadata": true}'

Files

read

Returns a file's raw content, optionally with its metadata.

Scope: files:read. Ask for metadata when you plan to edit: modified is the timestamp you pass back as expectedUpdatedAt.

{ "path": "/Projects/auth.py", "includeMetadata": true }

write

Creates a file, or overwrites one that already exists. Monofile keeps the previous content as a version, so you can restore it after an overwrite.

Scope: files:write. Two file types have their own tools because their content is machine-generated JSON. Use create_diagram for .draw and canvas_edit for .canvas, both on Content Tools.

{ "path": "/Projects/notes/plan.md", "content": "# Plan\n\n- [ ] draft\n" }

edit

Replaces an exact string inside a file. Prefer it to write on an existing file, because it changes one region and leaves the rest of the document alone.

Scope: files:write.

{
  "path": "/Projects/auth.py",
  "old_string": "def login(user):",
  "new_string": "def login(user, remember=False):"
}

The edit contract

The tool matches old_string literally. No regular expressions, no whitespace normalization, no case folding. Most failed calls trip on that, and each failure has its own code:

Shell

bash runs a command against your workspace. Read-only commands answer instantly. Everything else needs a real machine, so it runs in a sandbox, and the sandbox is part of paid plans.

The two tiers

The built-in shell is on every plan. A read-only chain of the commands below, joined by ;, && or ||, runs in-process straight against storage. It is instant and always sees the latest content.

One path per command, no glob expansion, and flag values are space-separated (-n 5, not -n5). This tier has no pipes, <, 2>, command substitution, background &, sed, awk, sort or interpreters.

The full shell is part of paid plans (Pro on a personal workspace, Team on an org workspace). Anything that is not a read-only built-in chain runs in a real sh with real coreutils, inside a persistent per-workspace sandbox whose disk mirrors your files. That is where pipes, redirects, sed, awk, sort, jq, git, python3, node and multi-line scripts work. Monofile writes the file changes the command leaves behind into the workspace as versioned edits, one changeset per call.

bash

The scope a command needs follows from what it does. Reading needs files:read. mkdir, mv, cp, touch and echo/printf with > need files:write. rm needs files:delete. The full shell checks the write-back diff, so a missing scope rejects the whole diff and writes nothing.

{"command": "grep -rn \"TODO\" /Projects --include=*.ts"}

curl -X POST "https://www.monofile.ai/api/tools/bash" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "grep -rn \"TODO\" /Projects --include=*.ts"}'

grep and find exit 1 when they match nothing. Treat that as an empty result.

What the result tells you

A built-in run returns output, exitCode and, on failure, stderr. A full-shell run adds these fields:

Errors you can plan for: SANDBOX_BUSY (one command per workspace at a time, retry), RATE_LIMITED, DIFF_TOO_LARGE (more than 200 changed files), INSUFFICIENT_CREDITS, SANDBOX_UNAVAILABLE and TIMEOUT.

Next steps