Home/Docs/macOS Guide/Command line (macOS)

macOS Guide

Command line (macOS)

Run a ProxyBridge profile on macOS without the window: the proxybridge command, its options, verbosity levels, output, every error message, the update check, and how to use it from scripts.

Command line

ProxyBridge for macOS can run without its window. The proxybridge command starts the same app in command line mode: it activates the system extension, sends it a profile, prints what is happening, and cleans up when you press Ctrl+C.

proxybridge --list-profiles
proxybridge --profile Work --verbose 2
cat lab.pbprofile | proxybridge --profile - --verbose 3

There is no second program. The command is a tiny launcher that the installer places in /usr/local/bin; it runs the app's own executable with --cli. You can also run the executable yourself:

/Applications/ProxyBridge.app/Contents/MacOS/ProxyBridge --profile Work

Starting the executable with no options opens the normal window. Starting it with any of the options below runs the command line mode instead. You do not need sudo: run it as yourself.

Options

Option What it does
--profile <name> Run a profile saved in the ProxyBridge app (see --list-profiles)
--profile - Read a profile (a .pbprofile file) from standard input
--list-profiles List the saved profiles and exit
--verbose <0-3> Output level: 0 silent (default), 1 log messages, 2 connections, 3 both
--update Check whether a newer version exists and exit
--version Print the version and exit
-h, --help Show the help and exit

Options can be written as --profile Work or --profile=Work, and --verbose=2. --cli is accepted and ignored (the launcher adds it). --profile is required to run: without it (and without --list-profiles, --update, --version or --help) the command stops with --profile is required. Use --help.

A first run

$ proxybridge --profile Work --verbose 2
ProxyBridge CLI 4.1.0
Extension: activating...
Extension: active
Network configuration: setting up (macOS asks you to allow it the first time)...
Profile "Work": 2 proxies, 5 rules applied
DNS proxy: on
Redirecting traffic. Press Ctrl+C to stop.
[10:21:04] TCP curl -> example.com:443 via SOCKS5 127.0.0.1:1080
[10:21:07] TCP Safari -> apple.com:443 via Direct
^C
Stopping...
Rules cleared, tunnel stopped.

What each line means:

Line Meaning
Extension: activating... Asking macOS to start the ProxyBridge system extension
Extension: waiting for your approval. Open System Settings > Privacy & Security and click Allow, then enter your password. This is needed once. The first time (or after a reinstall), macOS needs your approval. The command waits up to 5 minutes
Extension: active The extension is running
Network configuration: setting up ... The first run may show a macOS prompt to allow ProxyBridge's network configuration. Click Allow
Profile "Work": 2 proxies, 5 rules applied Your proxies and rules are loaded into the extension
DNS proxy: on or DNS proxy: off (host name rules and send hostname do not work) The profile's Enable DNS setting. When it is off, the command does not use the DNS proxy and switches ProxyBridge's own DNS entry off if it was on
Redirecting traffic. Press Ctrl+C to stop. Routing is on
Stopping... and Rules cleared, tunnel stopped. The clean shutdown after Ctrl+C

The first run needs someone at the Mac to approve the extension (see Install on macOS). After that, runs start straight away.

Profiles: saved, or from standard input

A saved profile

--profile Work runs the profile named Work that you saved in the app. The name must match exactly (including capitals). --list-profiles shows the names:

$ proxybridge --list-profiles
  Default
* Work
(* = the profile the app currently uses)

If you have never opened the app, there is nothing to list yet: No saved profiles. Open the ProxyBridge app once to create the default one.

The command reads the profile when it starts. Change the profile in the app and the command line does not follow: restart it. The command never changes your saved profiles. It also does not use the profile's closeToMenuBar and runAtStartup settings (they apply to the window only).

A profile name that contains a / or ends in .pbprofile is taken as a file path and refused (see below). Rename such a profile in the app.

A profile file, through standard input

The app is sandboxed, so it cannot open files in your folders. Pipe the file in instead:

cat ~/work.pbprofile | proxybridge --profile - --verbose 2
proxybridge --profile - < ~/work.pbprofile
  • Input is limited to 4 MB.
  • Standard input must be a pipe or a file. If it is the terminal, the command stops with a hint instead of waiting for you to type.
  • The file must be a macOS profile (see the format). A Windows or Linux profile is refused with an explanation.

Asking for a path directly (--profile ~/work.pbprofile) fails by design:

ERROR: Can't read '~/work.pbprofile'. The app is sandboxed and can't open files elsewhere. Use a saved profile name, or pipe the file in: cat ~/work.pbprofile | proxybridge --profile -

Verbosity

--verbose chooses what is printed while ProxyBridge runs.

Level Prints
0 (default) Only the start-up and shutdown lines
1 Plus log messages (the same as the Activity Logs tab: errors from proxies, warnings)
2 Plus connections (the Connections tab)
3 Both

Formats:

[10:21:04] TCP curl -> example.com:443 via SOCKS5 127.0.0.1:1080       (connection)
[10:21:07] UDP Safari -> unknown:unknown via Direct                    (connection)
[10:21:09] [ERROR] SOCKS5 connect rejected, REP=0x05 (connection refused)   (log message)

The time is when the line was printed. Text that comes from the network (process names, host names, proxy replies) is cleaned before it is printed: control characters, including terminal escape codes, are replaced by ?, so a hostile name cannot rewrite your terminal.

Level 2 and 3 turn traffic logging on in the extension, as the window does. The command checks for new lines once a second and reads more at once when a burst fills the buffer.

Profile errors

The command checks the whole profile before it touches the extension. If something is wrong it prints every problem it found and exits with code 1:

ERROR: The profile can't be used:
  - proxy x has the port 0, it must be 1-65535
  - proxy FTP x:0 has the type 'ftp', it must be socks5 or http
Message Meaning
The profile is not valid JSON. The input is not a JSON file
This does not look like a ProxyBridge macOS profile (no proxyConfigs or proxyRules). Profiles exported from the Windows app use a different layout and can't be loaded here. The file has neither of the two lists the macOS layout needs. This also happens with a Linux profile
The proxy list in the profile could not be read: ... proxyConfigs has the wrong shape (a missing id, type, host or port, or a wrong value type)
No saved profile named 'X' (available: A, B). Use --list-profiles. The name does not exist
the profile has N proxies, the limit is 100 Too many proxies
the profile has N rules, the limit is 5000 Too many rules
two proxies have the same id 'x' Proxy ids must be unique
a TYPE proxy has no host A proxy has an empty host
proxy HOST has the port N, it must be 1-65535 Port out of range
proxy TYPE HOST:PORT has the type 'X', it must be socks5 or http Unknown proxy type (written in either case)
proxy ... has a username or password longer than 255 bytes, SOCKS5 can't carry that SOCKS5 limit
rule N has the protocol 'X', it must be TCP, UDP or BOTH Wrong protocol in a rule (rule numbers start at 1)

Warnings do not stop the run. They are written to standard error as warning: ...:

Warning Meaning
rule N sends traffic to a proxy that is not in this profile, it will go direct The rule's action is not DIRECT, BLOCK or the id of a proxy in the file
the profile has no rules, nothing will be redirected No rules
rule N uses a host name, but DNS is off in this profile, so it will not match The profile has dnsEnabled set to false and rule N has a host name in its target hosts

After the profile is applied, the extension can still reject a rule it cannot read; the command then prints warning: N rule(s) were rejected by the extension (invalid fields).

Start-up and other errors

Message Meaning and what to do
The ProxyBridge app is running. Quit it first, only one of them can control the extension at a time. Quit the app (⌘Q) and run the command again
Another ProxyBridge CLI is already running. Only one command line at a time. Stop the other one first
Timed out waiting for the extension. Approve it in System Settings > Privacy & Security and run the command again. Nobody approved the extension in 5 minutes
macOS will finish activating the system extension after a restart. Restart your Mac and run the command again. macOS wants a restart to replace the old extension
The system extension could not be activated: ... macOS refused. The reason follows. See Troubleshooting
Could not load / save / reload the network configuration: ... macOS refused the network configuration, for example because you clicked Don't Allow
The tunnel did not start in 30 seconds. The extension did not come up. Run again; check System Settings
The tunnel was stopped by something else (is the ProxyBridge app running?). Nothing is being redirected any more. While the command ran, something stopped the tunnel. Opening the app does this, because the app takes over the extension. The command then exits with code 1
DNS proxy setup failed: ... (a warning) The DNS proxy could not be enabled. Domain rules and send hostname will not work, other rules do

Usage errors exit with code 2:

Message Meaning
Unknown option 'X'. Use --help. A misspelled or unsupported option
--profile requires a value. Use --help. You wrote --profile and nothing after it
--profile requires a profile name, or - to read from standard input. --profile= with an empty value
--verbose level must be 0-3. The level is not a number from 0 to 3

Exit codes

Code Meaning
0 Normal: help, version, list, update check, or a clean stop with Ctrl+C
1 An error (bad profile, start-up failure, the tunnel stopped)
2 A usage error

Checking for updates

$ proxybridge --update
Installed: v4.1.0
Latest:    v4.2.0
An update is available: <link to the installer package>
Release notes: <link to the release notes>

(The version numbers are an example.)

When you are up to date it prints You are up to date. The command only checks. It never downloads or installs anything: open the link, or use Help > Check for Updates... in the app. If the check fails the output is ERROR: Failed to check for updates: ... and the exit code is 1.

Stopping

Press Ctrl+C. The command:

  1. tells the extension to remove your rules and proxies,
  2. stops the tunnel,
  3. prints Rules cleared, tunnel stopped. and exits with 0.

SIGTERM (kill) and SIGHUP (closing the Terminal window) do the same. If the extension does not answer, the command exits anyway after 5 seconds. Closing the output (for example proxybridge ... | head) also stops it cleanly.

kill -9 (SIGKILL) cannot be caught. The command cannot clean up, and the rules stay active in the extension. Run the command again and press Ctrl+C, or open the ProxyBridge app and quit it. Both clear the rules.

Using it in scripts

#!/bin/bash
# route a build through a proxy, then clean up
LOG="$(mktemp)"
proxybridge --profile Build --verbose 1 > "$LOG" 2>&1 &
PB=$!
# wait until routing is on (the command prints this line when it is)
until grep -q "Redirecting traffic" "$LOG"; do sleep 1; done
./run-the-build.sh
kill -TERM "$PB"                # same as Ctrl+C: the rules are cleared
wait "$PB"
  • The command prints each line as soon as it is ready, so waiting for Redirecting traffic. in a log file or a pipe is reliable. Add a time limit to the loop in real scripts, in case the extension needs approval.
  • Keep a log: proxybridge --profile Lab --verbose 2 | tee connections.log.
  • Do the first run by hand at the Mac, so the extension is approved before a script depends on it.
  • It has been tested from a Terminal session. Running it from a system daemon is not covered here.

The command line and the window

The window (the app) and the command line control the same system extension, so only one can run at a time:

  • The command refuses to start while the app is running.
  • Opening the app while the command runs takes the extension over and stops the command (The tunnel was stopped by something else).
  • Two commands cannot run together either.

Removing the command

The installer adds /usr/local/bin/proxybridge. To remove it: sudo rm /usr/local/bin/proxybridge. The app itself is not affected.