Skip to content

CLI ​

Core is the process that does the routing. The desktop app starts and stops it for you. Run it yourself to validate a profile, to run Specola on a machine without a desktop, or to debug a start-up problem.

PlatformBinary
Windowsspecola-service.exe
macOS, Linuxspecola-core
bash
specola-core --test-config --config home.toml   # validate and exit
specola-core --config home.toml                 # run with this profile
specola-core                                    # run and wait for the app to choose a profile

On Windows, write specola-service.exe instead of specola-core. Started without any argument, the Windows binary prints a hint and exits with code 1; use --console to run it with no other option.

Options ​

OptionPlatformsMeaning
--config <file>allthe profile to load at start
--test-config, -tallload and validate --config, print the result, exit; Core does not start
--ipc-endpoint <path>alllisten on another local control endpoint (below)
--parent-pid <pid>allexit when that process exits; the desktop app passes its own PID. --parent-id is an old alias
--gateway <file>Linuxrouter mode (below)
--consoleWindowsrun in the foreground from a terminal; has no other effect
--serviceWindowsrun as the Windows service; only the Service Control Manager uses it
--reset-networkWindowsremove the DNS redirect a killed Core left behind, then exit; needs Administrator
-h, --helpallprint the options and exit
-v, --versionallprint the version and exit
  • A value can follow the option (--config home.toml) or be joined with = (--config=home.toml).
  • Options are exact: an unknown or misspelled option prints Unknown argument, the help, and exits with code 1. -t cannot be combined with other short flags.
  • There is no option for a data directory or a portable mode, and no way to set the log level on the command line; Core uses the folders listed under Files and folders.

--config ​

bash
specola-core --config /home/me/profiles/home.toml   # absolute path
specola-core --config home.toml                     # file name

A relative path is looked up in this order:

  1. the Profiles folder (~/.config/specola/profiles/home.toml on Linux),
  2. the folder of the executable.

The current directory is never used: specola-core --config ./home.toml run from your profile folder fails unless the file is also in one of those two places. Use an absolute path for a file elsewhere.

Inside the profile, relative paths of resource files (rule sets, geoip.dat, certificates) are resolved from the profile's own folder first; see Rules.

If the profile fails to load at a normal start, Core keeps running, reports the error to the app and the log, and waits for another profile. It does not exit.

--test-config ​

bash
specola-core -t --config home.toml
  • Prints Config validation passed: <path> and exits with 0, or prints Config validation failed: followed by every error and exits with 1.
  • Warnings, such as ignored sections, go to the log, not to the terminal.
  • It loads the profile exactly like a start: modules and disabled rules are applied, local resource files must exist, and remote rule sets and geo files are downloaded. When a download fails and a cached copy exists, the cached copy is used.
  • It needs no administrator rights and does not touch the network setup, so it is safe to run while another Core is running.
  • Without --config it exits with 2.

Local control endpoint ​

The app controls Core over a local channel. It is always open while Core runs.

PlatformDefault endpointWho can connect
Windowsnamed pipe \\.\pipe\specolathe user who started Core; when Core runs as the service or elevated, also SYSTEM, Administrators and every signed-in user
macOS, LinuxUnix socket /tmp/specola.sockthe user who started Core (file mode 0600); when Core runs as root, the user who asked for root

--ipc-endpoint changes it. It takes a socket path (/run/me/specola.sock), a pipe (\\.\pipe\name), or the URL forms unix:///path and pipe://name. The app must be pointed at the same endpoint.

Core is one instance per computer: a second Core exits with code 3 (Another specola-core process is already running). The control protocol is described in Control API; the optional TCP listener is api-listen.

Administrator rights ​

Enhanced Mode needs administrator (root) rights. On macOS and Linux, a Core started without them for a profile that enables Enhanced Mode asks for them once and starts again:

BuildHow Core asks
Linux releasepkexec, which shows the desktop's authentication dialog
macOS releasethe system administrator prompt; output goes to core-privileged-launch.log in the log folder
debug buildssudo in the terminal; with no terminal Core exits with code 1

Declining exits Core. On Windows the app starts Core through the service, which runs as LocalSystem.

Windows service ​

The installer registers a service named specola-service (display name "Specola Service"):

  • It runs specola-service.exe --service as LocalSystem, with manual start: the app starts it when it needs Core. Signed-in users may start, stop and query it; only administrators may change it.
  • It keeps its data in %ProgramData%\Specola, readable only by SYSTEM and Administrators. Profiles stay in each user's own folder; the app tells the service where they are.
  • When the service process ends without stopping properly (killed, crashed), Windows runs specola-service.exe --reset-network, which removes the NRPT rule that pointed system DNS at the TUN adapter. The service is not restarted.

Run --reset-network yourself from an Administrator terminal if DNS stops working after Core was killed:

powershell
& "C:\Program Files\Specola\specola-service.exe" --reset-network

It exits with 0 when the rule is gone (or there was none) and with 1 without Administrator rights.

Router mode ​

Linux builds can run Core as a transparent gateway for a LAN:

bash
specola-core --gateway /etc/specola/gateway.toml --config /etc/specola/profiles/router.toml
specola-core -t --gateway /etc/specola/gateway.toml   # validate the gateway file only

The gateway file configures the LAN interfaces, TPROXY capture, DHCP, the LAN DNS server and the control listener (lan-interfaces, local-domain, device, tproxy, dhcp, dns, api). Unless [api] enable = false, Core opens a control listener on the first LAN interface's IPv4 address, port 9090 (or [api] listen), before any profile loads, so a remote app can choose one. Like api-listen, it serves only private-network peers and has no authentication. A gateway file that does not load makes Core exit with code 2.

Files and folders ​

WindowsmacOSLinux
Data%LOCALAPPDATA%\Specola~/Library/Application Support/com.specola.Specola$XDG_CONFIG_HOME/specola (~/.config/specola)
Profiles<data>\profiles<data>/profiles<data>/profiles
Logs<data>\Logs~/Library/Logs/com.specola.Specola$XDG_STATE_HOME/specola/log (~/.local/state/specola/log)
Download cache<data>\Cache\remote~/Library/Caches/com.specola.Specola/remote$XDG_CACHE_HOME/specola/remote (~/.cache/specola/remote)

As the Windows service, the data folder is %ProgramData%\Specola and there is no Profiles folder of its own. When Core runs as root on macOS or Linux, the folders are those of the user who asked for root, not of root.

Release builds write nothing to the terminal after start-up: messages such as Cannot find --config go to the log file only. Look there when Core exits without a message. Debug builds also print to the terminal and keep a single specola.log that is overwritten at every start.

Environment variables ​

VariableEffect
SPECOLA_LOG_DIRwrites logs to this folder instead of the default log folder
XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_STATE_HOMELinux: move the data, cache and log folders; only absolute paths count
XDG_RUNTIME_DIRLinux: folder for runtime files, when it belongs to the user
LOCALAPPDATAWindows: an absolute path replaces the user's Local AppData folder (used by tests)

When Core asks for root itself, it passes these variables on to the new process.

Stopping Core ​

Ctrl+C, SIGTERM and closing the console window stop Core gracefully: Enhanced Mode is taken down and system DNS restored. If shutdown takes longer than 10 seconds, Core exits anyway. With --parent-pid, Core also stops when that process ends.

Exit codes ​

CodeMeaning
0normal stop, --help, --version, a passed --test-config, a successful --reset-network
1--test-config found errors; an unknown option or a missing value; the local control endpoint could not be opened; the gateway could not start; Windows: no argument given, --reset-network failed or lacks Administrator rights; macOS/Linux: asking for administrator rights failed
2Core's folders could not be created; --config not found; --test-config without --config; an invalid --parent-pid, or that process could not be watched; the --gateway file did not load
3another Core is already running on this computer
4the single-instance lock could not be taken for another reason

A profile that fails to load is not an exit: Core keeps running and waits for another one.