76 lines
3.8 KiB
Markdown
76 lines
3.8 KiB
Markdown
# User guide
|
||
|
||
## Profiles
|
||
|
||
A Proxy Profile contains proxy URLs and bypass rules. The Active Profile is the source applied to every Enabled Target.
|
||
|
||
Open Profile management with `m`:
|
||
|
||
- `n`: create a Profile
|
||
- `e` or Enter: edit the selected Profile
|
||
- `d`: safely delete the selected Profile
|
||
- Ctrl+S: save the editor
|
||
- Ctrl+T: switch between Single and Advanced modes
|
||
|
||
Single mode applies one URL to HTTP, HTTPS, and ALL/SOCKS. Advanced mode accepts separate values. A bare `host:port` is normalized to `http://`.
|
||
|
||
Bypass entries may be comma- or newline-delimited hostnames, domain suffixes, IPv4/IPv6 addresses, or CIDR ranges. The editor normalizes and deduplicates valid entries.
|
||
|
||
### Protocol Probe
|
||
|
||
Press Ctrl+D while editing the Single proxy URL to run an explicit handshake probe. It reports HTTP and SOCKS5 support without forwarding traffic or contacting another endpoint.
|
||
|
||
If both protocols are detected, the editor changes to Advanced mode and fills HTTP/HTTPS with `http://` and ALL/SOCKS with `socks5://`. GNOME cannot represent `socks5h` remote-DNS semantics; use Advanced mode with `socks5` when GNOME must use that endpoint.
|
||
|
||
## Dashboard
|
||
|
||
Press `p` to search and select the Active Profile. Select Targets with arrows or `j`/`k`; Space runs the contextual action:
|
||
|
||
- **Enable** a Disabled Target
|
||
- **Disable** an Enabled Target
|
||
- **Apply Profile** to an External Target
|
||
- **Resolve** a Drifted Target by reapplying the Active Profile or restoring the original configuration
|
||
|
||
Restoration refuses to overwrite configuration that changed after proxyctl applied it.
|
||
|
||
Other controls:
|
||
|
||
- `r`: refresh detection
|
||
- `u`: show unavailable Targets
|
||
- Tab: switch between Target list and details
|
||
- Page Up/Page Down: scroll details
|
||
- `e`: expand or collapse the current error
|
||
- `x`: acknowledge the current error
|
||
- `?`: contextual Help
|
||
- `q` or Esc: close the current page/dialog; `q` exits from the unobscured dashboard
|
||
- Ctrl+C: request exit
|
||
|
||
Conflicting actions are disabled while a mutation runs. Exit requests cancel cancellable work and wait for the operation to settle safely.
|
||
|
||
## Target states
|
||
|
||
- **Enabled:** managed configuration matches the Active Profile.
|
||
- **Disabled:** no managed or positively recognized external proxy configuration was detected.
|
||
- **External:** recognized proxy configuration exists outside proxyctl ownership.
|
||
- **Drifted:** managed configuration no longer matches the Active Profile, including partial failures.
|
||
|
||
External detection is best-effort. Disabled does not claim that every possible configuration source was exhaustively searched.
|
||
|
||
## What each Target affects
|
||
|
||
1. **Shell** — future commands in integrated Bash/Zsh sessions. It does not change existing processes or services.
|
||
2. **APT** — persistent Debian-family package operations through a tool-owned `apt.conf.d` overlay.
|
||
3. **Docker daemon** — registry and daemon traffic. Every change reloads systemd and restarts Docker.
|
||
4. **Docker containers/builds** — proxy defaults for future containers and builds in the owning user's Docker client configuration. It does not configure the daemon.
|
||
5. **GNOME** — compatible desktop applications using GNOME system proxy settings. It does not rewrite browser-specific profiles.
|
||
|
||
## Responsive and accessible TUI
|
||
|
||
At 100×28 and larger, Targets and details are side by side. At 60–99 columns they use one column. Below 60×16, proxyctl displays a minimum-size warning and restores interaction state after resize.
|
||
|
||
Focus and state never rely on color alone. States include symbols and words such as `● Enabled`, `○ Disabled`, `◇ External`, `! Drifted`, and `… Checking`. No Nerd Font is required. Set `NO_COLOR` to disable color.
|
||
|
||
Confirmation dialogs start on Cancel. The TUI uses the terminal alternate screen and restores the previous screen after exit.
|
||
|
||
Profiles are normally stored at `~/.config/proxyctl/profiles.json` with owner-only permissions.
|