Command line reference

The sxaccess binary is both the command line tool and the agent: the background service that keeps the device connected. Most commands hand their work to the running agent over a local socket, so the agent has to be installed and running; the install script sets up both. The CLI runs on Linux and macOS. On Windows, iOS and Android there is no CLI - those platforms use the app.

sxaccess help sorts the commands into three groups, and the three tables below follow it. sxaccess <command> --help lists the flags of one command.

start connects this device and keeps it connected. The first time, it signs the device in - in a browser, or with an enrollment key on a machine without one - and the device appears in the dashboard. After that the agent reconnects by itself, including after a reboot, so this is usually a one-time step. On success it prints This device is now connected.

If the device is already connected, start prints This device is already connected and changes nothing: an enrollment key and any settings you pass are ignored. The exception is naming another identity with --profile, which makes start reconnect with it. To change a setting, disconnect and connect again with the flag: sxaccess stop && sxaccess start --<flag>. --allow-server-ssh needs root, so use the command below for it. Run it as one line: a connection that goes through SXAccess, such as an SSH session to this machine, drops until start has finished. It does not work in a session opened with sxaccess shell: stopping the agent closes that session and ends the command, so use the console or an OpenSSH session.

The agent saves those settings with the identity in use, so they stay in force until you change them again; --block-inbound=false, for example, turns one off. On a machine where identity changes are turned off, the agent saves none of them, and start connects with the settings saved before; see agent below. While an organization you picked with sxaccess tenant switch is active, the agent runs on that organization's own configuration instead, so these settings are saved but not applied: see Move a device between organizations.

If the agent is not installed or not running, start answers cannot reach the SXAccess agent and prints the two commands that fix that. sxaccess agent info tells the two cases apart. If it prints Agent service: Stopped, the service is installed and only needs starting. If it reports the service is not installed, install it, then start it.

--no-browser, --profile and --tenant concern the sign-in, and enroll takes them too. The others are settings the agent saves with the identity. Two more flags control quantum resistance, an experimental option that only the CLI agent has; sxaccess start --help lists them, and How traffic is encrypted explains what they do.

This is the command you will run most. Without flags it starts with a headline that sums up the device's links to the management service and to Discovery: Connected, Partly connected (one of the two is down) or Not connected. Discovery is the service through which two devices agree on a path. Below it come this device's name and address, how many devices are connected, the routed networks in use, and the state of the Service, Discovery, the relays and the DNS servers. A device that is not signed in gets a short explanation and the command that fixes it instead.

-d adds the identity in use and whether the tunnel runs in the kernel or in user space. It also adds a block per device with its Path (P2P or Relayed), Candidates, Round trip, Last handshake, Transferred and the networks it Reaches; Troubleshooting the client explains how to read it. -d, --json, --yaml and --ipv4 are mutually exclusive. --ipv4 prints just this device's address, such as 100.72.0.33, and piping --json into jq -c gives one line per device. The four --filter-by-* flags narrow the list of devices by name prefix, address, state or path; any of them turns on the detail view by itself, and they narrow --json and --yaml too.

When your administrator publishes networks to this device - the resources of a network, or a route - the device can choose which of them to route to. That matters when a published range overlaps something already on your LAN: you can leave it out on one machine without changing the access rules for everyone. The device has to be connected.

reach list shows each network under its name in the dashboard, a resource's Name or a route's Network Identifier, with state: Selected or Not Selected. reach add takes those names and replaces the current selection with them; with -a it adds them to the selection instead. reach add all selects every published network, including ones published later. reach remove takes names or all.

An identity is one saved sign-in: its own key, its own settings, its own enrolment. Keep several to move between accounts on the same device without signing in again each time. Every machine has the built-in identity default, which cannot be removed; any other identity belongs to the user who added it. Only one identity is in use at a time.

identity add saves a new, empty identity. identity use switches to another one and disconnects the device if it is connected; sxaccess start then signs in with it the first time and connects. start --profile <identity> does both in one step. You cannot remove the identity in use.

To move between organizations your account belongs to, use the sxaccess tenant commands instead. While an organization picked there is active, its enrolment is the one the agent uses.

diagnose collect packs the agent's logs, the connection status and system details into one archive and prints Bundle saved to: with its path. diagnose capture <time> is the one to reach for with a fault that comes and goes. It switches the agent to trace logging and reconnects the device, so the capture starts from a fresh connection. It keeps running for the time you give, then builds the archive and puts the log level back. Because it reconnects, sessions running over SXAccess drop; a device that was disconnected is connected for the capture and disconnected again afterwards.

Both take -C, --log-file-count (how many rotated log files to include, default 1) and -S, --system-info (include system details, on by default). Add -A before you send an archive anywhere; What is in a bundle lists what it holds.

diagnose verbosity <level> changes how much the agent logs until it restarts: panic, fatal, error, warn, info, debug, trace. info is the default, so sxaccess diagnose verbosity info puts it back. diagnose keep-map on keeps the last network map the device received in memory, so the next archive includes it; capture turns it on by itself. diagnose trace has a page of its own: Trace why a connection is blocked.

The agent is the background process that keeps the device connected. It runs as a system service, and the install script registers and starts it, so you rarely need these commands. install, remove, start, stop, restart and reconfigure change the system service and need root; agent info only reports whether it is running (Agent service: Running). serve runs the agent in the foreground: it is what the system service and the Docker container run, not something you start by hand.

reconfigure registers the service again with the flags you give it. A running agent is stopped and started again, so there is nothing else to restart. --service-env gives the agent environment variables, and each run replaces the whole set: a second run does not add to the first, it takes its place. So list every variable the agent should have in one run, separated by commas, as in --service-env SX_RELAY_ONLY=true,SX_DISABLE_PROFILES=true; see Environment variables. -l sets the level the agent logs at, info unless you give it.

To turn identity changes off on a machine, give the service SX_DISABLE_PROFILES=true, as below. The agent then refuses to add, remove or switch identities. It also stops saving the settings that start passes, so start connects with the settings saved before. The --disable-profiles flag that sxaccess agent --help lists does not do this, because install and reconfigure do not pass it on to the service.

Every command accepts these, though only some use them. A matching SX_ environment variable overrides each of them - see Environment variables.

start also takes options that its help does not show. Use one when support, or another page of these docs, asks for it. Like the settings in Flags for start, they are saved with the identity, and a connected device ignores them, so disconnect and connect again in one line, as start shows.