Install
RedWatch needs Node.js 18 or newer. Check with node --version; if it's missing, install the LTS version from nodejs.org.
Windows (PowerShell)
macOS / Linux
The installer puts a single file in ~/.redwatch/bin and adds it to your PATH. Open a new terminal afterwards so the redwatch command is found.
Log in
Create an account and an API key in the dashboard, then run:
redwatch loginPaste your key when asked (it's hidden as you type) and press Enter at the API URL prompt to keep the default. RedWatch checks the key and saves it to ~/.redwatch/config.json, readable only by your user account.
First session
Go to a project folder and start the agent:
cd path/to/your-project
redwatchType a task and press Enter. RedWatch reads and searches files on its own, then asks before it edits anything or runs a command. For a single task without the interactive prompt:
redwatch "review src/ for injection bugs and list them by severity"Commands
| Command | What it does |
|---|---|
redwatch | Start an interactive session in the current folder. |
redwatch "<task>" | Run one task and exit. |
redwatch login | Save or replace your API key. |
redwatch logout | Remove the saved key from this machine. |
redwatch usage | Show credits used and remaining. |
-y, --yes | Approve edits and commands without asking (use with care). |
Inside a session
| Command | What it does |
|---|---|
/help | List commands. |
/clear | Start a fresh conversation (keeps you in the same folder). |
/auto | Toggle auto-approve for the rest of the session. |
/usage | Show your credit balance. |
/exit | Quit. Ctrl+C twice also exits. |
| Ctrl+C | Interrupt the agent mid-answer or mid-command. |
Tools & approvals
The agent works through six tools. Read-only tools run automatically; anything that changes your system waits for you.
| Tool | Approval | Purpose |
|---|---|---|
list_dir | automatic | List a folder. |
read_file | automatic | Read a file or a line range. |
search | automatic | Regex search across files (skips node_modules, .git, build output). |
write_file | asks | Create or overwrite a file. Shows the content first. |
edit_file | asks | Replace an exact snippet. Shows the diff first. |
run_command | asks | Run a shell command (PowerShell on Windows). Shows the command first. |
At each prompt answer y (yes), n (no) or a (always, for the rest of this session).
Good prompts
- Code review: "Audit the auth and session code for vulnerabilities. Rank by severity, fix the critical ones, run the tests."
- Incident response: "Here's
auth.log. Build a timeline of the suspicious logins and tell me whether the attacker got a shell." - Detection: "Write a Sigma rule for the PowerShell download cradle in
sample.ps1and explain what it catches and misses." - Hardening: "Review the Dockerfiles and Kubernetes manifests in
deploy/and fix insecure defaults." - Secrets: "Search this repo and its config files for hardcoded credentials and tell me what to rotate."
Be specific about scope. For any testing against live systems, say what you're authorized to test; see the acceptable use policy.
Configuration
Settings live in ~/.redwatch/config.json. Environment variables override the file:
| Variable | Meaning |
|---|---|
REDWATCH_API_KEY | API key to use instead of the saved one. |
REDWATCH_API_BASE | API base URL, for self-hosted or enterprise endpoints. |
REDWATCH_MODEL | Model id, if your plan offers more than one. |
NO_COLOR | Set to any value to turn off colored output. |
Billing & usage
Every request the agent makes uses a little of your credit balance, based on how much text it reads and writes. Long files and big command outputs cost more; /clear between unrelated tasks keeps requests small.
redwatch usageWhen your balance runs out the agent stops with an "out of credits" message. Top up in the dashboard and carry on with the same key.
Troubleshooting
| Problem | Fix |
|---|---|
redwatch not found | Open a new terminal after installing. On Windows, check %USERPROFILE%\.redwatch\bin is on your PATH. |
| "Your key was rejected" | Run redwatch login again and paste the full key, no spaces. |
| "Out of credits" | Top up in the dashboard. The key works again right away. |
| "Rate limited" | Wait a few seconds; you're sending requests faster than your plan allows. |
| Scripts disabled (Windows) | Run the installer with powershell -ExecutionPolicy Bypass -c "irm …/install.ps1 | iex". |
| Node too old | Install Node.js 18+ from nodejs.org and reopen the terminal. |