Build the Environment Note Before You Write the Question — A Small Shell Script for Posts That Get Replies

There are nights when I open the forum, start typing a question, and stall. I can describe what went wrong, but the follow-ups I know are coming — which version, which OS — mean stopping to look each one up.

So I wrote a script that does that part in a minute. One thing up front: the script collects the environment only. What you tried and what happened is yours to write. You need both for a question that actually gets read.

Questions that go unanswered are usually missing the same things

Picture yourself on the answering side. A post that says "it doesn't work" gives you almost nothing to act on. You can only ask back, and every round trip slows the reply.

Answerers usually want four things first.

Hand the top two rows to a machine and spend your time on the bottom two. That is the whole idea.

The script

As an indie developer I got tired of retyping uname and --version every time something broke, so I wrote a script that only prints them. What it solves: it lays out your environment in one go, and masks secret-looking strings that slipped into the log before you paste.

#!/usr/bin/env bash
# Usage: bash forum-report.sh [logfile]
# Prints an "environment note" to stdout. Masks the home path and token-like strings.
set -u
 
mask() {
  sed -E \
      -e "s#${HOME}#~#g" \
      -e 's#(ghp_|github_pat_|sk-|AIza)[A-Za-z0-9_-]{8,}#\1***#g' \
      -e 's#([Tt]oken|[Kk]ey|[Ss]ecret)=[^[:space:]]+#\1=***#g'
}
 
ver() {  # first line if the command exists, "not installed" otherwise
  if command -v "$1" >/dev/null 2>&1; then
    "$@" 2>&1 | head -n 1
  else
    echo "not installed"
  fi
}
 
{
  echo "## Environment"
  echo "- OS: $(uname -srm)"
  echo "- Shell: ${SHELL:-unknown}"
  echo "- agy: $(ver agy --version)"
  echo "- git: $(ver git --version)"
  echo "- node: $(ver node --version)"
  echo "- Checked at: $(date '+%Y-%m-%d %H:%M %Z')"
  if [ -n "${1:-}" ] && [ -f "$1" ]; then
    echo
    echo "## Log (last 40 lines)"
    echo '```'
    tail -n 40 "$1"
    echo '```'
  fi
} | mask

Three choices worth explaining:

• Everything goes through mask at the end. A machine catches a stray token more reliably than my eyes do at midnight.
• ver keeps only the first line. Multi-line version banners won't stretch the note, and "not installed" is itself a useful fact for the reader.
• The log is capped at 40 lines. A full dump buries the few lines that matter. If more is needed, the reader will ask.

What I actually verified

I ran this in a Linux sandbox. agy was not installed there, so that line printed "not installed". I have not seen how the version line looks on a machine with Antigravity installed. Please run it once yourself and read the output before you rely on it.

I fed it a dummy log:

error token=abc123 at /sessions/x
key=zzz ghp_ABCDEFGHIJKL1234 end

and got this back:

error token=*** at /sessions/x
key=*** ghp_*** end

Both the token= / key= shapes and the ghp_ prefix were masked. But only strings with a known shape are masked. Email addresses, internal hostnames, customer names, and project code names are untouched. Leave yourself time to read the note once more before posting.

Add lines that fit your own problem

ver takes the command and its arguments as-is, so extending the note is one line. If the symptom involves Python, for example, put this under node:

  echo "- python3: $(ver python3 --version)"

My rule of thumb is to add only what the symptom could plausibly touch; listing everything makes the reader hunt for the line that matters. When I can't tell whether something is relevant, I include it anyway — one extra line costs far less than a round of follow-up questions.

Three lines you write above the note

Once the note exists, add three lines on top. Borrow the shape, not my words.

1. What you were trying to do — one sentence
2. What you did and what came out — the steps and the key part of the error
3. What you already tried — briefly, including what changed nothing

The third line is the one people forget, and I suspect it helps answerers the most. "Restarted" or "updated the version" alone saves everyone from suggesting it again.

Let the machine carry the environment; carry the story yourself. I keep that split as a pre-post habit.

Lines to draw before you hit post

• Paste only after you have read the script's output with your own eyes.
• For private projects, rewrite the problem as a minimal example before posting.
• When it's solved, go back to the same thread and add one or two lines on the cause. It is the best clue you can leave for the next person with the same symptom.

To start, save the script as forum-report.sh and run it once now, so it is ready the next time something breaks.