remote_read
Read a file or 1-based line range from a remote host, returning paginated content plus SHA-256 hashes required for safe, conflict-checked edits.
Instructions
Read a file (or a 1-based line range) from a remote host with SHA-256 hashes.
Returns JSON with: content, file_hash, range_hash, start, end, total_lines, truncated. The file_hash MUST be supplied to remote_patch; if the file changed in between, remote_patch will refuse to overwrite.
The read is paged so a large file never has to come back as one
oversized blob: a single call returns at most limit lines (default
PORTAL_READ_MAX_LINES=2000) and at most PORTAL_READ_MAX_BYTES (default
16384) of content, whichever binds first — but always at least one line.
When the page stops before the requested end, truncated is true and
next_start gives the line to continue from (pass it back as start).
Pages are cut on line boundaries, so range_hash stays valid for patching.
Usage:
* Whole file (auto-paged): call remote_read(host, path); if the result
has truncated: true, call again with start=<next_start> and repeat
until truncated is false, concatenating each page's content in order.
* A specific range: remote_read(host, path, start=40, end=80) (still
paged if that range is huge).
* Just the first N lines: remote_read(host, path, limit=N) — handy to
peek the head of a big file without pulling it all.
Args:
host: SSH host alias (from ~/.ssh/config) or registered host name
path: Absolute remote path
start: 1-based starting line (default 1)
end: 1-based ending line of the requested range, inclusive
(default: end of file)
limit: max number of lines to return in this page (default: the
PORTAL_READ_MAX_LINES cap). The byte cap may shorten the page further.
encoding: Text encoding (default utf-8)
use_sudo: read via sudo cat (root) for a file the SSH user can't read
(root-owned / mode 600). The sudo password is resolved out-of-band
per host (never a parameter) and the result is flagged high_risk.
Exact bytes are preserved (no newline stripping) so file_hash stays
valid for remote_patch.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| host | Yes | ||
| path | Yes | ||
| limit | No | ||
| start | No | ||
| encoding | No | utf-8 | |
| use_sudo | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |