Report a problem

If something is wrong, run waired doctor first — it fixes most of it. This page is for what comes after: getting the evidence that lets somebody else work out what happened.

Turn on detailed logs before you reproduce it

Waired normally logs the important events only. The detail that explains a bug is not written down unless you ask for it first — so turning it on after the problem happened gives you a log of everything except the part you need.

Collect the diagnostics

1. Turn on detailed logs. This takes effect immediately, on both the background service and the Waired app. No restart.

   waired config log-level debug

2. Reproduce the problem. Do the thing that went wrong, the same way.

3. Collect the logs into one file.

   waired logs --mask-pii --since 30m -o report.txt

   --since is how far back to look — widen it if the problem happened a while ago. The default is one hour.

4. Turn the detail back off, so your logs stay small.

   waired config log-level info

report.txt holds the background service’s log and the AI engine’s log together. That one file is what to attach.

What --mask-pii does, and does not

It replaces four things with placeholders: your home folder, your username, your computer’s name, and the email address you signed in with.

It is best-effort, not a guarantee. It does not know about every path or name that could be personal to you — a project folder somewhere else on disk, a hostname you configured yourself, a URL you typed. Read the file before you attach it, whether or not you used the option.

It works on any command

waired logs --mask-pii masks that one command. To mask everything — including the installer and sign-in — set WAIRED_PII_MASK=1 in your environment instead. See Advanced install options.

When the problem happens during install

The steps above need Waired already installed. If it fails while installing, ask the installer for detailed logs from the start instead.

Linux / macOS

curl -fsSL https://github.com/waired-ai/waired-agent/releases/latest/download/install.sh \
  | sh -s -- --log-level debug --mask-pii

Windows

$env:WAIRED_LOG_LEVEL = 'debug'
$env:WAIRED_PII_MASK = '1'
iwr -useb https://github.com/waired-ai/waired-agent/releases/latest/download/install.ps1 | iex

The one-line form cannot take options, so set them as environment variables — they reach the installer and everything it runs, including the administrator step.

On Windows the installer also writes its own transcript to %TEMP%\waired-install.log. The administrator window closes when it finishes, so that file is often the only place the failure survives — attach it too.

Start over from a clean slate

If the setup looks confused rather than broken in one specific way, wiping and reinstalling in one step is often faster than diagnosing it.

This deletes things

A clean install permanently removes your settings, keys, local state, and the AI models you downloaded. You sign in again afterwards, and the models download again. It asks you to confirm first.

Linux / macOS

curl -fsSL https://github.com/waired-ai/waired-agent/releases/latest/download/install.sh \
  | sh -s -- --clean

Windows

$env:WAIRED_CLEAN = '1'
iwr -useb https://github.com/waired-ai/waired-agent/releases/latest/download/install.ps1 | iex

Full details, including how to wipe without reinstalling, are on Uninstall.

If you were asked to try a test build

Two options exist for this, and they combine.

• --edge / WAIRED_VERSION=edge — the latest build of the main branch, rebuilt on every change. Not a release. See Update Waired.
• --dev / -Dev — connects to Waired’s own development service instead of the normal one. This is for people working on Waired itself; a device registered this way does not appear in your normal account.

Linux / macOS

curl -fsSL https://github.com/waired-ai/waired-agent/releases/latest/download/install.sh \
  | sh -s -- --edge --dev --log-level debug

Windows

# Save the script first: the one-line form cannot pass -Dev.
$env:WAIRED_VERSION = 'edge'
$env:WAIRED_LOG_LEVEL = 'debug'
iwr -useb https://github.com/waired-ai/waired-agent/releases/latest/download/install.ps1 -OutFile $env:TEMP\install.ps1
& $env:TEMP\install.ps1 -Dev

The installer remembers which service you chose, on every operating system, so running waired init again later on this computer signs you back in to the same one — you do not have to repeat --dev or --control.

To get back to a normal install afterwards, do a clean install as above (the --stable option alone changes the build, not which service you are registered with).

What to attach

report.txt	From the four steps at the top
waired version --json	Exact build
waired doctor output	What it found, even if it fixed it
Windows install failures	%TEMP%\waired-install.log
What you expected	And what happened instead

File it at github.com/waired-ai/waired-agent/issues.