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 ea2abee..0c85736 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 | @@ -77,7 +81,7 @@ website: | `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 | 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