bux-fetch

# bux fetch — read the operator's machine You are operating across **two computers**, and you must use both: 1. **Your own machine** (this VPS/sandbox). Explore it normally with `ls`, `cat`, `grep`, etc. 2. **The operator's machine** (their laptop) — reachable **only** through `bux fetch`. This is where the operator's real code, configs, notes, and data usually live. **Do not assume everything you need is on your own machine.** A large fraction of the useful context — the project the operator is actually working on, their local files, their configuration — exists on *their* laptop, not yours. When a task refers to "my project", "my files", "the repo on my machine", or anything you can't find locally, reach for `bux fetch` before concluding the information doesn't exist. ## What it is `bux fetch` asks the operator's laptop to perform a **read-only** operation. Each request is shown to the operator, who **approves or denies** it; approved requests run with read-only primitives (there is no way to write, edit, delete, or execute anything on their machine). ``` bux fetch list <path> # like `ls` on the operator's machine bux fetch read <path> # like `cat` (text files; large files are truncated) bux fetch grep <pattern> <path> # like `grep -rn` (regexp, recursive, read-only) bux fetch get <path> [dest] # copy a file from the operator's machine to here ``` Examples: ``` bux fetch list ~/Projects bux fetch read ~/Projects/app/README.md bux fetch grep "def main" ~/Projects/app # find where something is defined/used bux fetch get ~/Projects/app/data.csv ./data.csv ``` `grep` takes a Go/RE2 regexp and searches a file or a whole directory tree, returning `path:line:text`. It skips binary files and noise dirs (`.git`, `node_modules`, …) and stops at 500 matches — so it's the cheapest way to *locate* something before reading. Any absolute or `~`-relative path is allowed — the operator decides per request. ## Use it EFFICIENTLY — every call costs the operator a click A human approves each request, so calls are **slow, interruptive, and may be denied**. Treat the operator's attention as the scarce resource: - **Locate before reading.** Use `grep` to find which files matter (one approval searches a whole tree), then `read` only those — far cheaper than reading dozens of files to find one. - **Explore top-down.** `list` a directory first, then do a few **targeted** `read`s — don't read dozens of files speculatively. - **Pull once.** If you need to work over a file repeatedly, `get` it to your machine once and then use it locally — don't `read` the same file again and again. - **Ask for what you need, not what you might need.** No scattershot reads "just in case". - **A denial is a normal answer.** If a request comes back `denied`, do **not** retry it or rephrase and ask again — move on, and tell the operator what you were trying to do and why. - **Batch your reasoning, not the network.** Decide the few files that actually matter, then request those. ## What it is NOT - It is **not** a way to modify the operator's machine. Writes/edits are impossible by design — don't try. - It is **not** your own filesystem. `bux fetch list ~` reads the *operator's* home, not yours. ## Enabling it — tell the operator how You don't set anything up; the operator does, from their laptop. If `bux fetch` reports it **can't reach the operator**, they're just not sharing right now. Don't retry in a loop — instead, **tell the user exactly how to enable it**: > To let me read files from your machine, run `bux share` on your laptop. It serves the > approvals and auto-connects this box — nothing else to run. If this box has never been provisioned for read access, they run `bux setup <project> <box>` once first (or `bux share --setup <project> <box>` to do both at once). Then wait for them to do it — a failed `bux fetch` is a normal "not sharing yet" state, not an error to work around.