Agent command reference

This page lists the commands the Outpost agent accepts on the endpoint, the options of the Windows installers, and the environment variables the agent reads. Most endpoints never need any of them: the installer and the console do the work. Use this page for scripted deployment, golden images, and troubleshooting.

Where the agent is

Platform	Agent binary
Windows	C:\Program Files\Outpost\Agent\outpost-agent.exe
Linux, FreeBSD, OpenBSD	/opt/outpost/outpost-agent
macOS (Preview)	/usr/local/outpost/outpost-agent

Run every command except version as an administrator (Windows) or root. On Windows, run, install, uninstall, and reset ask for elevation if you start them without it.

Commands

Command	What it does
enroll	Enrolls this computer with a token, writes its configuration and certificate, and exits. It does not install or start the service.
run	Runs the agent in the foreground. The service runs the same command, so run in a terminal reproduces what the service does.
install	Registers the agent as a service that starts at boot and restarts on failure, then starts it. With --token and --server, it enrolls first.
uninstall	Stops and removes the service. On Linux, FreeBSD, OpenBSD, and macOS it also retires the endpoint. See uninstall.
import-config <path>	Applies the connection settings in an agent.json from a downloaded installer. See import-config.
reset	Removes this computer’s enrollment identity, to prepare a golden image. See reset.
update	Checks for a newer agent and tray now and installs it. See update.
version	Prints outpost-agent and the version.

enroll

outpost-agent enroll --server <your-server-url> --token <enrollment-token>

Flag	Value
--token	Required. An enrollment token from Issue token only in the console.
--server	Required unless OUTPOST_SERVER_URL is set. The server URL the console shows with the token, starting with https://.

On success it prints enrolled: followed by the endpoint’s identifiers.

run

Flag	Value
--server	Overrides the server URL in the configuration for this run.

Only one copy of the agent runs at a time. A second copy exits with code 3.

install

Flag	Value
--token	Optional. Enroll with this token before installing.
--server	Optional. The server URL for enrollment.

• On Windows, install registers the OutpostAgent service only and refuses if it already exists. Use the installers for a complete Windows install.
• On Linux, FreeBSD, OpenBSD, and macOS, running install over an installed agent refreshes the service definition and exits with code 5. The tarball’s install.sh treats that as an upgrade and restarts the service.

uninstall

Flag	Value
--keep-data	Linux, FreeBSD, OpenBSD, and macOS. Keeps the configuration and enrollment identity, so a reinstall comes back as the same endpoint.

On Linux, FreeBSD, OpenBSD, and macOS, uninstall stops and removes the service, tells your Outpost that the endpoint is retired, and deletes /etc/outpost, including the certificate and private key. It does not delete the agent binary.

On Windows, outpost-agent uninstall removes the OutpostAgent service only. To remove Outpost from a Windows computer, see Retire or uninstall the agent.

On Linux, uninstall refuses on an agent installed from a .deb or .rpm package and names the package command to use instead.

import-config

outpost-agent import-config agent.json

• The file must be valid JSON with a server_url.
• If the computer is enrolled to the client the file names, nothing changes.
• If it is enrolled to a different client, the old certificate and key are removed and the new settings replace the old ones.
• After applying the file, the agent deletes it, because it holds a single-use enrollment token.

reset

Flag	Value
--force	Applies the reset. Without it, reset reports what it would change and changes nothing.
--token	Plants an enrollment token, so every computer deployed from the image enrolls itself on first boot.

reset removes the certificate, private key, and pinned server certificate, and clears the endpoint’s identity from the configuration. It keeps the server URL and the reporting intervals. See Prepare a golden image.

update

outpost-agent update [--check] [--json]

Flag	Value
--check	Reports whether a newer build is available and installs nothing.
--json	Prints the result as JSON.

update asks the running service to run the same check it runs every 4 hours, and waits up to 90 seconds for the service to come back on the new version. If the service does not answer, the command updates the agent itself and restarts the service. It must run as an elevated administrator (Windows) or root.

Exit code	Meaning
0	Up to date, or updated.
1	The check, the install, or the restart failed.
2	Bad flags.
10	With --check: a newer agent or tray is available.
11	Not run as an elevated administrator or root.
12	Nothing done: the last update is still being checked, or another update is running.

Windows single-file installer

outpost-agent-setup.exe installs the agent, the watchdog, and the tray app, and applies the configuration built into it.

Option	What it does
--dangerously-silent-installation	Skips the consent panel. For deployment tools only.
--skip-config	Installs without applying the built-in configuration. The computer does not enroll until you give it a token.
--dir <path>	Installs to another folder. The default is C:\Program Files\Outpost\Agent.
--uninstall	Removes Outpost from the computer and retires the endpoint.
--keep-data	With --uninstall, keeps the configuration and enrollment identity.
--version	Prints the version and exits.

Exit code	Meaning
0	Installed or uninstalled.
1	The person at the computer declined at the consent panel.
2	Bad command-line arguments.
3	The installer’s payload is missing or unreadable.
4	The built-in configuration is missing or unusable. Download a new installer, or use --skip-config.
5	The install failed. Details are in %TEMP%\outpost-setup.log.
6	Not run with administrator rights.

Windows MSI property

Property	What it does
SKIPCONFIG=1	Installs without the agent.json that must otherwise sit beside the MSI. The computer does not enroll until you give it a token.

Environment variables

The agent takes its settings from its configuration file. These are the exceptions:

Variable	Effect
OUTPOST_SERVER_URL	The server URL for enroll and run. A --server flag takes precedence, and this takes precedence over the configuration file.
OUTPOST_LOG_LEVEL	debug, info (the default), warn, or error.
OUTPOST_DATA_DIR	Moves the agent’s data directory, which holds its configuration, certificate, and logs.
HTTPS_PROXY	An HTTP proxy for the agent’s outbound connections. Takes precedence over the proxy in the configuration.

Related

• Deploy the agent at scale
• Retire or uninstall the agent
• Troubleshoot the agent