diff options
Diffstat (limited to 'docs/usage.html')
| -rw-r--r-- | docs/usage.html | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/docs/usage.html b/docs/usage.html index 031bc4e..6d770d0 100644 --- a/docs/usage.html +++ b/docs/usage.html @@ -167,6 +167,75 @@ termux-wake-unlock</code></pre> <code>git clone</code> command. <a href="https://workingcopy.app/">Working Copy</a> is a GUI alternative that can also clone a public HTTPS repository without an account.</p> +<h2 id="pi">Automating with the pi agent</h2> +<p><code>pi</code> is a terminal coding agent (a Node CLI — <code>pi --help</code>). Everything below uses +only documented flags, treats the mirror as read-only, and was run against <code>pi 0.80.3</code> before being +written down.</p> + +<h3>1. One-shot: analyse a file, print an answer, exit</h3> +<pre><code>git clone --depth 1 https://newos.webx11.duckdns.org/newos4.git /tmp/newos4 + +pi -p --no-session --no-tools --model gemma4:31b-cloud \ + @/tmp/newos4/README.md "In one sentence, what is this repository?"</code></pre> +<p style="color:var(--dim);font-size:.9rem">Output: <em>“This repository contains newOS4, a browser-based +terminal featuring a filesystem, command shell, editor, and AI agent backed by WebDAV storage and WebX11 user +spaces.”</em> — <code>-p</code> is the non-interactive mode, <code>@file</code> inlines the file, +<code>--no-tools</code> forbids tool use entirely, <code>--no-session</code> leaves nothing behind.</p> + +<h3>2. Machine-readable output for scripts</h3> +<pre><code>pi -p --no-session --no-tools --mode json --model gemma4:31b-cloud \ + @/tmp/newos4/CHANGELOG.md "Summarise the newest release in one line" \ + | jq -r 'select(.type=="message_end" and .message.role=="assistant") + | .message.content[0].text'</code></pre> +<p style="color:var(--dim);font-size:.9rem"><code>--mode json</code> emits one JSON object per line. The event +types in order are <code>session</code>, <code>agent_start</code>, <code>turn_start</code>, +<code>message_start</code>/<code>message_end</code> (the assistant's text is in +<code>message.content[].text</code>), <code>turn_end</code>, <code>agent_end</code>. Parse on +<code>message_end</code> and you never have to scrape the terminal UI.</p> + +<h3>3. Let it read the tree — with a read-only tool allowlist</h3> +<pre><code>cd /tmp/newos4 +pi -p --no-session --tools read,bash --no-approve --model gemma4:31b-cloud \ + "Which files does main.html load, and where is the module loader defined?"</code></pre> +<p style="color:var(--dim);font-size:.9rem">Tool names are <code>read</code>, <code>bash</code>, +<code>edit</code>, <code>write</code>; <code>--tools</code> is an allowlist, so leaving <code>edit</code> and +<code>write</code> out makes the run read-only by construction. <code>--tools read</code> alone cannot list a +directory — <code>read</code> reads files — so add <code>bash</code> when it needs to <code>ls</code>.</p> + +<h3>Flags worth knowing for automation</h3> +<table> + <tr><th>Flag</th><th>What it buys you</th></tr> + <tr><td><code>--list-models</code></td><td>What your install can actually reach, with context and output limits</td></tr> + <tr><td><code>--model</code></td><td>Pin the model in scripts. A saved default can be retired server-side and fail with HTTP 410 “was retired” — passing <code>--model</code> keeps a job reproducible</td></tr> + <tr><td><code>--offline</code></td><td>Skip startup network calls (<code>PI_OFFLINE=1</code> also works)</td></tr> + <tr><td><code>--session-id</code> / <code>--continue</code></td><td>Resume the same conversation across runs instead of re-sending context</td></tr> + <tr><td><code>--append-system-prompt <file></code></td><td>Append text or a file's contents to the system prompt — the cheap way to give every run your house rules</td></tr> + <tr><td><code>--skill <path></code></td><td>Load a skill file or directory; <code>--no-skills</code> / <code>--no-context-files</code> turn discovery off</td></tr> +</table> + +<h3>Safety: this repository is untrusted input</h3> +<div class="warn"> + <code>pi</code> auto-loads project files (<code>AGENTS.md</code>, <code>CLAUDE.md</code>, skills, extensions) + from the working directory. For a clone of a public repository you did not write, run with + <code>--no-approve</code> (ignores project-local files) and a tool allowlist that cannot write — + <code>--tools read</code>, or <code>--tools read,bash</code> if it must list files. Never point a + full-tool run at a repo you have not read: a prompt-injection in a README is executed the same way your own + instructions would be. +</div> + +<h3>A cron-able digest</h3> +<pre><code>#!/bin/sh +# nightly: refresh the mirror, ask one question, write markdown +set -eu +cd /tmp/newos4 2>/dev/null || git clone -q --depth 1 https://newos.webx11.duckdns.org/newos4.git /tmp/newos4 +git pull -q --ff-only +pi -p --no-session --no-tools --mode json --model gemma4:31b-cloud \ + @CHANGELOG.md "Three bullets: what changed in the newest release?" \ + | jq -r 'select(.type=="message_end" and .message.role=="assistant") | .message.content[0].text' \ + > "$HOME/newos4-digest.md"</code></pre> +<p style="color:var(--dim);font-size:.9rem">The mirror only fast-forwards, so <code>git pull --ff-only</code> +can never wedge. Nothing here can push — the repository refuses <code>receive-pack</code> at three levels.</p> + <h2 id="updating">Updating later</h2> <pre><code>cd newos4 git pull --ff-only # the mirror only ever fast-forwards |