Pult Docs
Pult Agent

CLI Reference

Reference for the Pult Agent command-line flags used by deployment scripts and admin tooling.

This page documents every command-line flag accepted by the Pult Agent binary. Use it when writing deployment scripts, MDM post-install hooks, or troubleshooting an existing install.

Binary location

PlatformPath
macOS/Applications/Pult Agent.app/Contents/MacOS/pult-agent
WindowsC:\Program Files\Pult Agent\pult-agent.exe

The shorthand pult-agent in this page refers to the platform binary above. Substitute the full path in deployment scripts.

General behavior

  • The agent runs as a long-lived process that starts at login: on Windows through the login auto-start entry the MSI adds, on macOS through the LaunchAgent the .pkg installs (see macOS Auto-Start). The flags below are short-lived invocations of the same binary that perform a one-shot action.
  • Most flags exit immediately after doing their work without starting the long-lived agent process. Per-flag notes call out any exceptions.
  • Flags that read or write OS secure storage (Keychain on macOS, Credential Manager on Windows) require an active, interactive user session: the binary cannot run pre-login. Per-flag notes call this out where it applies.

--bootstrap-token <token>

Sets or updates the bootstrap token in secure storage. The next time the agent loads the token (after a restart or --reload-bootstrap-token), it creates a new device authentication request with it, unless it is signed in.

  • Validates the token format: 1-128 characters, alphanumeric with - and _ allowed.
  • Stores the token in OS secure storage.
  • Stops waiting for any earlier request from this device. That request stays under Pending Device Requests until an admin reviews it.
  • Does not start the agent.

Usage:

pult-agent --bootstrap-token "your-token-here"

Notes:

  • The agent does not notice this command if it is already running. To pick up the new token in a running process, follow it with --reload-bootstrap-token, or restart the agent.
  • If the same token is already stored, the command exits successfully with a message and makes no change.
  • An invalid token format prints Invalid bootstrap token provided and exits non-zero.

--reload-bootstrap-token

Signals a running agent to reload its bootstrap token from secure storage.

  • If the agent is not running, the command starts the agent, which then uses the stored token. Run it in the employee's user session, like the agent itself, not as SYSTEM or root.
  • Typically combined with --bootstrap-token in deployment scripts to update a token in place without restarting.

Usage:

pult-agent --reload-bootstrap-token

--reset-bootstrap-token

Removes the stored bootstrap token and stops waiting for any pending request from this device. A running agent picks this up after --reload-bootstrap-token or a restart. The agent needs a bootstrap token again before it can enroll by bootstrapping.

Usage:

pult-agent --reset-bootstrap-token

--cleanup-credentials

Removes the stored user access token, whether it came from manual sign-in or from an accepted device authentication request.

Use this to "fully de-enroll" the agent before re-running enrollment, e.g. when validating a deployment recipe end-to-end. Combine with --reset-bootstrap-token to also clear the stored bootstrap token.

Usage:

pult-agent --cleanup-credentials

Common compositions

Set + reload (rotating a token on a running agent)

pult-agent --bootstrap-token "new-token"
pult-agent --reload-bootstrap-token

Full de-enrollment (testing a deployment recipe)

pult-agent --reset-bootstrap-token
pult-agent --cleanup-credentials

After running these, the agent has no stored token and no access token, equivalent to a fresh install for enrollment purposes.

See also

Last updated on

On this page