---
title: "Agent command reference"
description: "Every outpost-agent command and flag, the Windows single-file installer's options, the MSI property, environment variables, and exit codes."
url: "https://support.outpostplatform.com/agent/cli/"
product: "agent"
type: "reference"
status: "draft"
ai_summary: "outpost-agent verbs: enroll, run, install, uninstall, import-config, reset, update, version, with flags and exit codes (update 0, 1, 2, 10, 11, 12; install 5 means already installed). outpost-agent-setup.exe flags: --uninstall, --keep-data, --dir, --skip-config, --dangerously-silent-installation, --version. MSI SKIPCONFIG=1. Variables OUTPOST_SERVER_URL, OUTPOST_LOG_LEVEL, OUTPOST_DATA_DIR."
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/agent/cli.md"
license: "CC BY 4.0"
---

# 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](#uninstall). |
| `import-config <path>` | Applies the connection settings in an `agent.json` from a downloaded installer. See [import-config](#import-config). |
| `reset` | Removes this computer's enrollment identity, to prepare a golden image. See [reset](#reset). |
| `update` | Checks for a newer agent and tray now and installs it. See [update](#update). |
| `version` | Prints `outpost-agent` and the version. |

### enroll

```sh
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 {#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](/agent/retire-and-uninstall/).

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

### import-config {#import-config}

```sh
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 {#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](/agent/deploy-at-scale/#golden-images).

### update {#update}

```sh
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 {#setup-exe}

`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](/agent/deploy-at-scale/)
- [Retire or uninstall the agent](/agent/retire-and-uninstall/)
- [Troubleshoot the agent](/agent/troubleshooting/)