From c7936201b6f8609a4aa9cf29550c6018a564e706 Mon Sep 17 00:00:00 2001 From: Negative Star Innovators Date: Fri, 2 Oct 2026 08:28:15 +1300 Subject: [PATCH 1/2] docs: add user-facing CLI reference (docs/cli.md) and link it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The agentredactor CLI (the engine binary's second mode) had no user-facing documentation anywhere — the only complete reference was the maintainer-oriented CLI section of windows/AGENTS.md, mixed with internals that do not belong in user docs. - docs/cli.md: full user reference, verified against core/src/cli.cpp (command surface, keys, PII types, exit codes, Linux-only update and uninstall with --yes) plus scripting examples; internals (Hello transport, test hooks) stay in AGENTS.md - README.md: three-line CLI pointer at the end of the Documentation section - linux/README.md / windows/README.md: cross-links to docs/cli.md - windows/AGENTS.md: anti-drift note — update docs/cli.md when cli.cpp changes --- README.md | 4 ++ docs/cli.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++ linux/README.md | 3 +- windows/AGENTS.md | 5 ++ windows/README.md | 4 +- 5 files changed, 146 insertions(+), 2 deletions(-) create mode 100644 docs/cli.md diff --git a/README.md b/README.md index ea2abee..5e2184f 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,10 @@ website: - [OpenCode](https://agentredactor.negativestarinnovators.com/opencode.html) - [Hermes](https://agentredactor.negativestarinnovators.com/hermes.html) +The engine binary also doubles as a scriptable CLI (`agentredactor status`, +`keywords add`, `profiles add`, …) for terminals, scripts, and headless +machines — see [docs/cli.md](docs/cli.md). + ## Repository layout | Path | Contents | diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..2faf1f4 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,132 @@ +# Agent Redactor CLI + +The Agent Redactor engine binary doubles as a command-line interface. On +Windows it ships as `agentredactor.exe` next to the GUI (the Microsoft Store +package also registers an `agentredactor` AppExecutionAlias); on Linux the +installer symlinks `agentredactor` into `~/.local/bin`, and AppImage +invocations are forwarded to the same binary. + +Every command talks to the *running* engine over its localhost control API, so +the CLI and the GUI always agree on state — use either, interchangeably. + +- Output goes to the console, or UTF-8 to stdout when piped (script-friendly). +- Exit codes: `0` success, `1` runtime error, `2` usage error. +- `agentredactor help` prints the built-in reference; it is always in sync + with the binary you have installed. +- Quote regex patterns containing `{ } [ ]` etc. so the shell does not expand + them — bash: single quotes, PowerShell/cmd: double quotes, e.g. + `agentredactor regex add 'sk-[a-zA-Z0-9]{20,}'`. + +## Commands + +### Overview + +```text +agentredactor status engine + profile overview (ungated) +agentredactor languages list supported UI language codes (ungated) +agentredactor download-model download the AI model weights (first run; shows progress) +``` + +On Linux, `status` additionally checks the update feed and prints an +"update available" line when a newer release exists. + +### Settings and profiles + +```text +agentredactor get [--profile P] read a setting +agentredactor set [--profile P] change a setting +agentredactor profiles list list profiles (with request/redaction stats) +agentredactor profiles add [--port N] [--upstream-url U] [--api-key K] +agentredactor profiles delete +``` + +- `--profile P` selects a profile by list number, id, or alias (optional when + only one profile exists). +- Without `--port`, `profiles add` picks the first free port from 8080 and + prints the created profile's id. +- `profiles delete` accepts only the profile id (never an alias or list + number) and refuses to delete the last profile. + +Global keys: `start-on-boot`, `logging`, `show-sensitive`, `app-language`. + +Profile keys: `alias`, `upstream-url`, `api-key`, `port`, +`confidence-threshold` (0..1), `use-ai-model`. + +`app-language` must be an exact supported BCP-47 tag — the values are what +`agentredactor languages` prints (`en`, `de`, `zh-CN`, …); a partial tag like +`zh` is rejected. + +### Redaction lists (profile-scoped) + +```text +agentredactor regex list [--profile P] +agentredactor regex add [--profile P] +agentredactor regex remove [--profile P] +agentredactor keywords list [--profile P] +agentredactor keywords add [--ignore-case] [--profile P] +agentredactor keywords remove [--ignore-case] [--profile P] +agentredactor pii-types list [--profile P] +agentredactor pii-types enable | disable [--profile P] +``` + +- `pii-types` deals in single PII types only (no categories): `account_number`, + `private_address`, `private_date`, `private_email`, `private_person`, + `private_phone`, `private_url`, `secret`. +- Duplicates are rejected on add: a keyword is a duplicate when both text and + case-sensitivity match; a regex when the normalized pattern matches + (`{,5}` == `{0,5}`). +- `keywords remove ` selects a case-insensitive entry with + `--ignore-case`; without it, the first case-sensitive match, falling back to + an ignore-case entry. + +### Security + +```text +agentredactor password enable +agentredactor password disable +``` + +- **Windows:** enables/disables Windows Hello protection. With protection on, + every read/write command demands a fresh Hello consent (`status` and `help` + stay open). +- **Linux:** enables/disables a typed master password. With protection on, + every read/write command prompts for it (`status` and `help` stay open). + +### Maintenance (Linux only) + +```text +agentredactor update check for and install AppImage updates +agentredactor uninstall [--yes] remove Agent Redactor, settings, icons, and the AppImage +``` + +`update` swaps the AppImage for the latest release on its update channel; +restart to apply (`systemctl --user restart agentredactor` on headless +installs). `uninstall` asks for confirmation unless `--yes` is given. + +## Scripting examples + +```bash +# Is the engine up? (on Linux this also reports when an update is available) +agentredactor status + +# Add a keyword from a script; a duplicate is rejected with a clear message +agentredactor keywords add "internal-codename" --ignore-case + +# Turn off phone-number redaction on the default profile +agentredactor pii-types disable private_phone + +# Headless server: point a new agent profile at OpenRouter +agentredactor profiles add openrouter \ + --upstream-url https://openrouter.ai/api/v1 --api-key sk-or-... + +# Review the result +agentredactor profiles list +``` + +## Notes + +- There is deliberately no `engine run` / `engine stop`: engine lifecycle + belongs to the GUI (or the systemd user service on headless Linux). +- On Linux the model weights download automatically on first engine start; + `download-model` exists so a fresh headless install can bootstrap without + waiting (`install.sh` already runs it for you). diff --git a/linux/README.md b/linux/README.md index e7457b1..b9e7032 100644 --- a/linux/README.md +++ b/linux/README.md @@ -1,7 +1,8 @@ # Agent Redactor — Linux build For installing and *using* Agent Redactor (end users), see the -[root README](../README.md) — this document covers building and developing +[root README](../README.md), and for the scriptable `agentredactor` CLI see +[docs/cli.md](../docs/cli.md) — this document covers building and developing on Linux. Build the engine/CLI (`agentredactor`) and the Qt GUI (`agentredactor-gui`) diff --git a/windows/AGENTS.md b/windows/AGENTS.md index ac11219..532cf90 100644 --- a/windows/AGENTS.md +++ b/windows/AGENTS.md @@ -67,6 +67,11 @@ Key sources: ## CLI +The user-facing CLI reference lives in `../docs/cli.md` — update it when +`../core/src/cli.cpp` changes. The notes below are maintainer detail (password +model, transport quirks, test hooks) that intentionally stays out of the user +docs. + `agentredactor.exe` doubles as the CLI; every subcommand talks to the running engine over the control API (so CLI and GUI always agree). Output goes to the inherited console, or UTF-8 to stdout when piped (script/AI-agent friendly); diff --git a/windows/README.md b/windows/README.md index 5fc2ace..cdb4cbe 100644 --- a/windows/README.md +++ b/windows/README.md @@ -107,7 +107,9 @@ From the `windows` folder: ## Configuration -Settings are stored in `%APPDATA%\AgentRedactor\settings.json`. +Settings are stored in `%APPDATA%\AgentRedactor\settings.json`. Everything in +this section can also be driven from the scriptable `agentredactor` CLI — +see [../docs/cli.md](../docs/cli.md). ### Default Profile Setup From 532c84cb01a3ba428105530402b13991a2b2c177 Mon Sep 17 00:00:00 2001 From: Negative Star Innovators Date: Fri, 2 Oct 2026 08:39:02 +1300 Subject: [PATCH 2/2] docs: point the docs/ README row at the CLI reference; drop planning-doc gitignore entry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs/ row still referenced the Linux implementation spec and port plan, which are not tracked (internal planning docs, deleted from the working tree) — docs/cli.md is the only tracked doc today. Also remove the now-dead .gitignore entry for docs/linux-port-plan.md. --- .gitignore | 3 --- README.md | 2 +- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index a840ab3..459e677 100644 --- a/.gitignore +++ b/.gitignore @@ -27,9 +27,6 @@ cloudflare/.dev.vars # Store submission content (kept out of the repo) windows/store-listing/ -# Internal planning docs (not for public release) -docs/linux-port-plan.md - # Translation/CI tooling venv (lrelease, deep-translator) .transvenv/ diff --git a/README.md b/README.md index 5e2184f..0c85736 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ machines — see [docs/cli.md](docs/cli.md). | `core/` | OS-agnostic C++ core (HTTP proxy, ONNX NER, regex/redaction engines, CLI) shared by the platform frontends; built by both the Windows and Linux projects | | `cloudflare/` | The Cloudflare worker + R2 behind the self-release channel (`/install.ps1`, `/install.sh`, `/updates`, `/models`) | | `website/` | The website with the agent integration guides, translated into every supported language | -| `docs/` | Design and spec documents (Linux implementation spec, port plan) | +| `docs/` | Additional documentation — currently the [CLI reference](docs/cli.md) | | `tests/` | pytest suites: cross-platform `cli/` and `migration/`, Linux GUI tests in `linux/` (AT-SPI), Windows GUI end-to-end tests in `gui/` (FlaUI + mock LLM), self-release install/upgrade E2E | | `third_party_tests/` | Integration tests driving real third-party agent CLIs through the proxy | | `scripts/` | Build/release helpers and scripts that configure third-party clients for the integration tests |