amnezia-vpn/amnezia-client

Fork 0

mirror of https://github.com/amnezia-vpn/amnezia-client.git synced 2026-10-15 05:42:07 +00:00

[PR #3096] Add local JSON CLI control interface #3074

New issue

Open

opened 2026-10-14 21:07:19 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-14 21:07:19 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/amnezia-vpn/amnezia-client/pull/3096
Author: @witqq
Created: 8/30/2026
Status: 🔄 Open

Base: dev ← Head: feature/stream-deck-cli

📝 Commits (2)

088905e feat: add local CLI control interface
b38a895 fix: route CLI through connection workflow

📊 Changes

14 files changed (+596 additions, -53 deletions)

View changed files

📝 client/CMakeLists.txt (+16 -0)
📝 client/amneziaApplication.cpp (+152 -21)
📝 client/amneziaApplication.h (+19 -1)
📝 client/cmake/sources.cmake (+2 -0)
📝 client/core/controllers/connectionController.cpp (+5 -0)
📝 client/core/controllers/connectionController.h (+1 -0)
📝 client/core/controllers/coreController.cpp (+127 -0)
📝 client/core/controllers/coreController.h (+3 -0)
➕ client/core/utils/cliControlProtocol.cpp (+114 -0)
➕ client/core/utils/cliControlProtocol.h (+45 -0)
📝 client/main.cpp (+24 -31)
📝 client/mozilla/localsocketcontroller.cpp (+16 -0)
📝 client/mozilla/localsocketcontroller.h (+4 -0)
➕ client/tests/cliControlProtocolTest.cpp (+68 -0)

📄 Description

Summary

add a versioned JSON command-line interface for status, list-servers, connect, disconnect, and toggle;
forward commands from a secondary invocation to the already running GUI over the existing per-user local application socket;
route connection changes through the existing connection UI workflow and preserve an activation requested while the daemon socket is still initializing;
add a focused protocol parser/serialization test, enabled with AMNEZIA_BUILD_CLI_CONTROL_TESTS.

Example commands:

AmneziaVPN --status
AmneziaVPN --list-servers
AmneziaVPN --connect <stable-server-id>
AmneziaVPN --disconnect
AmneziaVPN --toggle

Every response is one JSON line with version: 1 and ok. The server list exposes only stable IDs, display names, and the default marker.

Motivation and consumer

The interface allows desktop integrations to control the existing AmneziaVPN process instead of automating the GUI or starting a second client instance.

The first consumer is the open-source Amnezia Stream Deck plugin. An installable macOS/Windows preview was published before this PR: v0.1.0-preview.1.

Local security model

no TCP listener or remote-control service is added;
QLocalServer::UserAccessOption restricts the control socket to the current OS user;
requests are handled inside the existing GUI process and reuse its server and connection controllers;
responses do not include server configurations, credentials, private keys, or connection secrets.

Verification

macOS arm64: full AmneziaVPN target built; cli-control-protocol passed 1/1;
Windows x64 with Qt 6.10.1/MSVC 2022: full AmneziaVPN target built; cli-control-protocol passed 1/1;
Stream Deck consumer: 7/7 unit tests passed on macOS and Windows;
Stream Deck protocol E2E passed on both platforms with a non-networking CLI fixture, covering registration, status rendering, Connect/Toggle responses, and rejected server IDs without changing a real VPN connection.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/amnezia-vpn/amnezia-client/pull/3096 **Author:** [@witqq](https://github.com/witqq) **Created:** 8/30/2026 **Status:** 🔄 Open **Base:** `dev` ← **Head:** `feature/stream-deck-cli` --- ### 📝 Commits (2) - [`088905e`](https://github.com/amnezia-vpn/amnezia-client/commit/088905e96834090daad08a495cdab41c56b7ae63) feat: add local CLI control interface - [`b38a895`](https://github.com/amnezia-vpn/amnezia-client/commit/b38a895bb0cf2c34088268f9e2ee86182ae9b0d1) fix: route CLI through connection workflow ### 📊 Changes **14 files changed** (+596 additions, -53 deletions) <details> <summary>View changed files</summary> 📝 `client/CMakeLists.txt` (+16 -0) 📝 `client/amneziaApplication.cpp` (+152 -21) 📝 `client/amneziaApplication.h` (+19 -1) 📝 `client/cmake/sources.cmake` (+2 -0) 📝 `client/core/controllers/connectionController.cpp` (+5 -0) 📝 `client/core/controllers/connectionController.h` (+1 -0) 📝 `client/core/controllers/coreController.cpp` (+127 -0) 📝 `client/core/controllers/coreController.h` (+3 -0) ➕ `client/core/utils/cliControlProtocol.cpp` (+114 -0) ➕ `client/core/utils/cliControlProtocol.h` (+45 -0) 📝 `client/main.cpp` (+24 -31) 📝 `client/mozilla/localsocketcontroller.cpp` (+16 -0) 📝 `client/mozilla/localsocketcontroller.h` (+4 -0) ➕ `client/tests/cliControlProtocolTest.cpp` (+68 -0) </details> ### 📄 Description ## Summary - add a versioned JSON command-line interface for `status`, `list-servers`, `connect`, `disconnect`, and `toggle`; - forward commands from a secondary invocation to the already running GUI over the existing per-user local application socket; - route connection changes through the existing connection UI workflow and preserve an activation requested while the daemon socket is still initializing; - add a focused protocol parser/serialization test, enabled with `AMNEZIA_BUILD_CLI_CONTROL_TESTS`. Example commands: ```text AmneziaVPN --status AmneziaVPN --list-servers AmneziaVPN --connect <stable-server-id> AmneziaVPN --disconnect AmneziaVPN --toggle ``` Every response is one JSON line with `version: 1` and `ok`. The server list exposes only stable IDs, display names, and the default marker. ## Motivation and consumer The interface allows desktop integrations to control the existing AmneziaVPN process instead of automating the GUI or starting a second client instance. The first consumer is the open-source [Amnezia Stream Deck plugin](https://github.com/witqq/amnezia-stream-deck). An installable macOS/Windows preview was published before this PR: [v0.1.0-preview.1](https://github.com/witqq/amnezia-stream-deck/releases/tag/v0.1.0-preview.1). ## Local security model - no TCP listener or remote-control service is added; - `QLocalServer::UserAccessOption` restricts the control socket to the current OS user; - requests are handled inside the existing GUI process and reuse its server and connection controllers; - responses do not include server configurations, credentials, private keys, or connection secrets. ## Verification - macOS arm64: full `AmneziaVPN` target built; `cli-control-protocol` passed 1/1; - Windows x64 with Qt 6.10.1/MSVC 2022: full `AmneziaVPN` target built; `cli-control-protocol` passed 1/1; - Stream Deck consumer: 7/7 unit tests passed on macOS and Windows; - Stream Deck protocol E2E passed on both platforms with a non-networking CLI fixture, covering registration, status rendering, Connect/Toggle responses, and rejected server IDs without changing a real VPN connection. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-14 21:07:19 +00:00

No labels

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

amnezia-vpn/amnezia-client#3074

No description provided.

Rows
Columns