Rpeek

Remote diagnostics via rpeek

Preconditions

• rpeek is on PATH.
• Connection details — a host (or host:port; the port defaults to 7017) and a token, both required — come from one of two sources, in this precedence:
  1. Positional args to this skill, invoked as /rpeek <host> <token>. Both are mandatory; the token is never optional.
  2. The environment: RPEEK_HOST and RPEEK_TOKEN, if already exported. If a host or token is missing from both, ask the user — never guess a host or fabricate a token.
• Confirm reachability and authorization with a cheap call (rpeek hostname) before a long investigation; it needs no jail and its output names the host that answered.

Applying the connection details

Shell state does not persist between calls and no token file is used, so the host and token must accompany every rpeek invocation:

• Given as positional args to the skill: prefix each call inline via environment variables — RPEEK_HOST=<host> RPEEK_TOKEN=<token> rpeek <tool> [args] — reusing the same values for every call this session.
• Already exported in the environment: call rpeek <tool> [args] directly. Pass the token only through RPEEK_TOKEN, never via --token.

Discovering the tools

The toolset is self-describing — do not rely on a hardcoded list, since it can change between versions:

• rpeek help — lists the available tools, each with a one-line summary.
• rpeek help <tool> — prints that tool's arguments and flags with their defaults and meanings.

Run rpeek help first whenever you are unsure what is available or what a tool accepts; it is the authoritative reference. Every tool is READ-ONLY, and help needs no host or token.

How to use

Every invocation is one-shot: rpeek <tool> [args], carrying the connection details as described above. A tool's own flags and its path may appear in any order (rpeek read /p --max-bytes 200 and rpeek read --max-bytes 200 /p are equivalent). Read stdout as if it were the output of the equivalent Unix command; it is already formatted server-side. On a non-zero exit, read stderr and adapt — do not retry the identical command.

Representative calls (connection prefix omitted for brevity; see rpeek help <tool> for each tool's full argument set):

rpeek hostname
rpeek version
rpeek list /var/log
rpeek read /etc/nginx/nginx.conf --max-bytes 20000
rpeek grep /var/log --pattern "ERROR" --ignore-case
rpeek tail /var/log/nginx/error.log --lines 200
rpeek stat /etc/hosts
rpeek ps
rpeek disk
rpeek journal --unit nginx --lines 100
rpeek db-list
rpeek db-tables --db app
rpeek db-schema --db app orders
rpeek sql --db app "SELECT state, COUNT(*) AS n FROM orders GROUP BY state ORDER BY n DESC"

Databases

When the answer lives in an application database (row counts, joins, "how many are stuck in failed?"), the server may expose read-only database access by alias. You never supply a DSN — only the alias the operator configured. Work in this order:

1. rpeek db-list — the entry point: shows the configured aliases with engine and host. Nothing to query means no databases were configured; ask the user, do not guess a DSN.
2. rpeek db-tables --db <alias> — the tables and views you may read.
3. rpeek db-schema --db <alias> <table> — a table's columns, types, and nullability, so you use real column names.
4. rpeek sql --db <alias> "<query>" — run the query. Quote the whole query as one argument.

The query language looks like SQL but is a restricted, SELECT-only subset: SELECT with joins, WHERE, GROUP BY, ORDER BY, and LIMIT, plus the aggregates COUNT, SUM, AVG, MIN, MAX. Writes, subqueries, comments, multiple statements, and other functions are not available — do not attempt them. Run rpeek help sql for the exact grammar before composing non-trivial queries; if a query is rejected or reports an unknown table or column, read the message and fix the query rather than retrying it unchanged.

Rules

• Use only the tools rpeek help reports. Do not invent flags or tools; there is no write, delete, restart, or "run command" capability, by design.
• Paths are the host's real paths and must fall inside a jail root the operator granted. A "not within any allowed root" error means the directory was not granted — report that to the user; do not try to tunnel around it.
• Patterns are RE2 (Go regexp), not shell globs.
• If output ends with ... (truncated) (stderr notes truncation), narrow the query (tighter --pattern, larger --max-bytes with --offset paging, fewer --lines) rather than assuming you saw everything.
• If the tool is not sufficient to solve the user's task, ask them for help. Eg. for manually running tools or edit files.

Exit codes

0 success · 1 protocol/transport error · 2 server-returned error (bad path, unauthorized, tool error) · 3 usage error. A 2 with "unauthorized" means the token is wrong — stop and ask the user; do not brute-force.

Working a problem

1. Establish context — resolve the host and token (skill positional args or the environment); sanity-check with hostname (or disk/ps). Missing/rejected token → stop and ask the user.
2. Map the question to tools — "is the service up?" → ps / journal --unit; "why is it erroring?" → tail then grep the log; "is the box full?" → disk.
3. Run, read, refine — each call returns pre-formatted text; interpret it and choose the next call. Calls are cheap and read-only, so breadth-first probing is fine.
4. Respect the boundaries — jail/auth/truncation errors are signals to change approach or ask the user, never to escalate. There is nothing to escalate to.
5. Report — synthesize findings, citing the concrete evidence (tail lines, grep hits) rather than raw dumps.

Example (user: "nginx is down on the prod box, why?"):

rpeek ps                                  # is nginx running? -> not in the table
rpeek journal --unit nginx --lines 50     # why did it stop? -> "bind() to :443 failed"
rpeek grep /etc/nginx --pattern "listen"  # what claims 443? -> two server blocks
rpeek disk                                # rule out a full disk -> plenty free
# -> report: duplicate `listen 443` in <file:line>; nginx aborts on bind conflict.