CLI Scripting Guide

The WebStream server binary, webstream.exe, doubles as an administration CLI. Beyond starting services, it provisions organizations, users, groups, applications, workspaces, and policies, and it performs import/export and database maintenance — making it the basis for repeatable, scriptable setup and infrastructure-as-code.

Overview

On a default install the binary lives at C:\WebStream\webstream.exe. Run it from that directory, or use the full path. To see the authoritative, version-specific command list at any time, run:

webstream.exe -help

Administration commands (as opposed to service modes) require built-in authentication: <authentication><enabled>true</enabled><mode>builtin</mode> in app.config.xml. In workgroup, enterprise (SSO), or disabled modes, user and IAM commands are refused — see Authentication modes below.

How to read this guide

Every command entry lists its synopsis, its parameters, a usage example, related commands, and exit codes. In synopses:

<angle-brackets> mark a required argument.
[square-brackets] mark an optional argument.
Parameters marked * in a table are required.

Examples use deliberately simple test- prefixed identifiers so you can follow along on a fresh server, matching the Guided Walkthrough. Note that policy names are normalised to lowercase with underscores (for example test_lowtrust).

Exit codes

Code	Meaning
`0`	Success (also returned by `-help`).
`1`	Unknown command, invalid arguments, authentication disabled or wrong mode, or execution failure.
`2`	Usage or unknown-target error — returned only by `-db-restore`.

Scripts should check the process exit code after each call. In PowerShell that is $LASTEXITCODE.

Tip

Wrap literal values that contain spaces in double quotes, for example "Test User" or "C:\Apps\test-app.exe".

Service modes

These options start a long-running server role rather than run a one-shot command. They do not return an administrative exit code on normal shutdown. On a single-server deployment all roles run together; on distributed deployments each role is started separately (usually as a Windows service — see AWS Deployment Patterns).

Option	Alias	Role
`-gateway`	`-gw`	Gateway server: SSL termination and load balancing.
`-backend`	`-be`	Backend server: registers with the gateway and hosts sessions.
`-sessionmanager`	`-sm`	Session manager.
`-accessmanagement`	`-am`	Access management server: IAM and authentication API. Also required for import/export and database commands.
`-metricsengine`	`-me`	Metrics engine server.
`-tags <list>`	—	Comma-separated backend image tags, for example `gpu,autocad`.
`-devmode`	—	Run in development mode.

# Start the gateway role
webstream.exe -gw

Authentication commands

These manage the built-in authentication accounts that IAM users are mapped to. They require built-in auth mode.

`-add-user`

Create a new authentication account. This is the credential a person signs in with; map it to an IAM user with -add-iam-user.

webstream.exe -add-user <username> <password> [email]

Parameter	Description
`username` *	At least 3 characters; letters, digits, dots, dashes, underscores.
`password` *	At least 8 characters.
`email`	Optional contact email.

# Create a test sign-in account
webstream.exe -add-user test-username TestPass123! test-user@example.com

Related: -add-iam-user, -reset-password, -list-users · Exit codes: 0 success; 1 on invalid arguments, auth disabled, or execution error.

`-remove-user`

Delete an authentication account. Use when offboarding a person or cleaning up test accounts.

webstream.exe -remove-user <username>

Parameter	Description
`username` *	The account to remove.

webstream.exe -remove-user test-username

Warning

Removal is permanent. Detach the account from IAM users and groups first to avoid orphaned mappings.

Related: -add-user, -delete-iam-user · Exit codes: 0 success; 1 on error.

`-list-users`

List all authentication accounts. Handy for verifying provisioning or auditing who can sign in.

webstream.exe -list-users

webstream.exe -list-users

Related: -add-user, -list-iam-users · Exit codes: 0 success; 1 on error.

`-reset-password`

Set a new password for an account, for example after a forgotten-password request.

webstream.exe -reset-password <username> <newpassword>

Parameter	Description
`username` *	The account to update.
`newpassword` *	New password; at least 8 characters.

webstream.exe -reset-password test-username NewPass456!

Related: -add-user, -enable-mfa · Exit codes: 0 success; 1 on error.

`-enable-mfa` / `-disable-mfa`

Turn multi-factor authentication on or off for an account.

webstream.exe -enable-mfa <username>
webstream.exe -disable-mfa <username>

Parameter	Description
`username` *	The account to change.

webstream.exe -enable-mfa test-username

Related: -reset-password, -list-users · Exit codes: 0 success; 1 on error.

IAM: Organizations

`-add-org`

Create an organization (tenant). Everything else — users, groups, apps, workspaces, policies — belongs to an organization.

webstream.exe -add-org <name> [description]

Parameter	Description
`name` *	Organization name.
`description`	Optional description.

# Create a test organization
webstream.exe -add-org test-org "Sandbox for CLI testing"

Related: -init-org-defaults, -list-orgs · Exit codes: 0 success; 1 on error.

`-init-org-defaults`

Seed the default groups and policy sets into an organization that already exists. Use it to bring an older or manually-created org up to the standard baseline.

webstream.exe -init-org-defaults <org-name>

Parameter	Description
`org-name` *	The organization to seed.

webstream.exe -init-org-defaults test-org

Related: -add-org, -list-policies · Exit codes: 0 success; 1 on error.

`-list-orgs`

List all organizations.

webstream.exe -list-orgs

webstream.exe -list-orgs

Related: -add-org · Exit codes: 0 success; 1 on error.

IAM: Users

`-add-iam-user`

Create an IAM user in an organization and map it to an authentication account. Provision people here before assigning them to groups and workspaces.

webstream.exe -add-iam-user <display-name> <org-name> <auth-username> [email]

Parameter	Description
`display-name` *	Human-readable name.
`org-name` *	Target organization.
`auth-username` *	Existing authentication account to link (see `-add-user`).
`email`	Optional contact email.

# Create a test IAM user linked to the test-username account
webstream.exe -add-iam-user "Test User" test-org test-username test-user@example.com

Related: -add-user, -add-user-to-group, -list-iam-users · Exit codes: 0 success; 1 on error.

`-delete-iam-user`

Remove an IAM user from an organization. The underlying authentication account is not removed — use -remove-user for that.

webstream.exe -delete-iam-user <username> <org-name>

Parameter	Description
`username` *	The IAM user to remove.
`org-name` *	Organization the user belongs to.

webstream.exe -delete-iam-user test-username test-org

Related: -add-iam-user, -remove-user · Exit codes: 0 success; 1 on error.

`-list-iam-users`

List IAM users, optionally scoped to one organization.

webstream.exe -list-iam-users [org-name]

Parameter	Description
`org-name`	Optional organization filter. Defaults to `default`.

webstream.exe -list-iam-users test-org

Related: -add-iam-user, -list-group-members · Exit codes: 0 success; 1 on error.

IAM: Groups

`-add-group`

Create a group. Groups are how workspaces are granted to people, so users are added to groups and groups are granted workspaces.

webstream.exe -add-group <group-name> <org-name> [description]

Parameter	Description
`group-name` *	Group name.
`org-name` *	Target organization.
`description`	Optional description.

webstream.exe -add-group test-group test-org "Test group for CLI walkthrough"

Related: -add-user-to-group, -grant-workspace, -list-groups · Exit codes: 0 success; 1 on error.

`-list-groups`

List groups, optionally scoped to one organization.

webstream.exe -list-groups [org-name]

Parameter	Description
`org-name`	Optional organization filter.

webstream.exe -list-groups test-org

Related: -add-group · Exit codes: 0 success; 1 on error.

`-add-user-to-group`

Add an IAM user to a group, granting them everything the group can access.

webstream.exe -add-user-to-group <user> <group> <org>

Parameter	Description
`user` *	IAM user (auth username).
`group` *	Target group.
`org` *	Organization both belong to.

webstream.exe -add-user-to-group test-username test-group test-org

Related: -add-group, -list-group-members · Exit codes: 0 success; 1 on error.

`-list-group-members`

List the members of a group. Use it to confirm membership after provisioning.

webstream.exe -list-group-members <group> <org>

Parameter	Description
`group` *	Group to inspect.
`org` *	Organization the group belongs to.

webstream.exe -list-group-members test-group test-org

Related: -add-user-to-group, -list-iam-users · Exit codes: 0 success; 1 on error.

IAM: Applications

`-add-app`

webstream.exe -add-app <name> <version> <exe-path> <org> [description] [args] [icon]

Parameter	Description
`name` *	Application name.
`version` *	Version label.
`exe-path` *	Full path to the executable on the session host.
`org` *	Target organization.
`description`	Optional description.
`args`	Optional command-line arguments.
`icon`	Optional icon reference.

webstream.exe -add-app test-app "1.0" "C:\Apps\test-app.exe" test-org "Test application"

Related: -add-app-to-workspace, -list-apps · Exit codes: 0 success; 1 on error.

`-list-apps`

List registered applications, optionally scoped to one organization.

webstream.exe -list-apps [org-name]

Parameter	Description
`org-name`	Optional organization filter.

webstream.exe -list-apps test-org

Related: -add-app · Exit codes: 0 success; 1 on error.

IAM: Workspaces

`-create-workspace`

Create a workspace — the unit of delivery that groups are granted access to.

webstream.exe -create-workspace <name> <type> <org> [description]

Parameter	Description
`name` *	Workspace name.
`type` *	Workspace type, for example `AppCollection`.
`org` *	Target organization.
`description`	Optional description.

webstream.exe -create-workspace test-ws AppCollection test-org "Test workspace"

Related: -add-app-to-workspace, -grant-workspace, -list-workspaces · Exit codes: 0 success; 1 on error.

`-list-workspaces`

List workspaces, optionally scoped to one organization.

webstream.exe -list-workspaces [org-name]

Parameter	Description
`org-name`	Optional organization filter.

webstream.exe -list-workspaces test-org

Related: -create-workspace · Exit codes: 0 success; 1 on error.

`-add-app-to-workspace`

Place a registered application into a workspace.

webstream.exe -add-app-to-workspace <app> <version> <workspace> <org>

Parameter	Description
`app` *	Application name.
`version` *	Application version.
`workspace` *	Target workspace.
`org` *	Organization all belong to.

webstream.exe -add-app-to-workspace test-app "1.0" test-ws test-org

Related: -add-app, -create-workspace · Exit codes: 0 success; 1 on error.

`-grant-workspace`

Grant a group access to a workspace. This is the step that makes a workspace appear for its members after sign-in.

webstream.exe -grant-workspace <workspace> <group> <org>

Parameter	Description
`workspace` *	Workspace to grant.
`group` *	Group receiving access.
`org` *	Organization both belong to.

webstream.exe -grant-workspace test-ws test-group test-org

Related: -create-workspace, -add-group · Exit codes: 0 success; 1 on error.

IAM: Policies

`-create-policy`

Create a policy set. Policy names are normalised to lowercase with underscores.

webstream.exe -create-policy <name> <org> [description]

Parameter	Description
`name` *	Policy set name (normalised, for example `test_lowtrust`).
`org` *	Target organization.
`description`	Optional description.

webstream.exe -create-policy test_lowtrust test-org "Test low-trust policy"

Related: -assign-policy, -list-policies · Exit codes: 0 success; 1 on error.

`-list-policies`

List policy sets, optionally scoped to one organization.

webstream.exe -list-policies [org-name]

Parameter	Description
`org-name`	Optional organization filter.

webstream.exe -list-policies test-org

Related: -create-policy · Exit codes: 0 success; 1 on error.

`-assign-policy`

Assign a policy set to a workspace, applying its governance to sessions launched from that workspace.

webstream.exe -assign-policy <policy> <workspace> <org>

Parameter	Description
`policy` *	Policy set to assign.
`workspace` *	Target workspace.
`org` *	Organization both belong to.

webstream.exe -assign-policy test_lowtrust test-ws test-org

Related: -create-policy, -grant-workspace · Exit codes: 0 success; 1 on error.

Bulk export

`-export-iam-config`

Export an organization's full IAM configuration to a JSON file, for backup or to seed another environment.

webstream.exe -export-iam-config <org> <output.json>

Parameter	Description
`org` *	Organization to export.
`output.json` *	Destination file path.

webstream.exe -export-iam-config test-org test-org-config.json

Related: -export-users, -export-workspaces · Exit codes: 0 success; 1 on error.

Import / Export

These per-entity import and export commands must be run in access-management mode (prefix the command with -am). Each accepts the same options.

Option	Description
`-org <orgId>`	Organization to act on. Defaults to `default`.
`-file <path>`	JSON file path. Defaults to `<entity>.json` (for example `users.json`).

Available pairs: -export-users / -import-users, -export-groups / -import-groups, -export-applications / -import-applications, and -export-workspaces / -import-workspaces.

# Export the default org's users to users.json
webstream.exe -am -export-users

# Export a named org to a specific file
webstream.exe -am -export-users -org test-org -file test-users.json

# Import workspaces from a file into the default org
webstream.exe -am -import-workspaces -file test-workspaces.json

Note

These commands only run under -am. Without it they return exit code 1 with guidance.

Related: -export-iam-config, -db-backup · Exit codes: 0 success; 1 on error.

Database administration

These commands maintain the PostgreSQL databases (IAM, metrics, activity) and must be run in access-management mode (-am). See Components for how these databases fit together.

`-db-status`

Report the health of each database. Use it as a quick pre-flight check or in monitoring scripts.

webstream.exe -am -db-status

webstream.exe -am -db-status

Related: -db-backup · Exit codes: 0 when all databases are healthy; 1 if any check fails.

`-db-backup`

Dump the databases to disk. Run it on a schedule for point-in-time recovery.

webstream.exe -am -db-backup [-out <dir>]

Option	Description
`-out <dir>`	Output directory. Defaults to `{InstallDir}\backups`.

webstream.exe -am -db-backup -out C:\WebStream\backups

Related: -db-restore, -db-status · Exit codes: 0 success; 1 if any dump fails.

`-db-restore`

Restore a single database from a dump file. Both options are required.

webstream.exe -am -db-restore -file <dump> -target <iam|metrics|activity>

Option	Description
`-file <dump>` *	Path to the dump file to restore.
`-target <name>` *	Which database to restore: `iam`, `metrics`, or `activity`.

webstream.exe -am -db-restore -file C:\WebStream\backups\iam_20260101.dump -target iam

Warning

Restoring overwrites the target database. This command returns exit code 2 for usage errors or an unknown target (as opposed to the usual 1), and 0/1 for the restore result itself.

Related: -db-backup, -db-status · Exit codes: 0 success; 1 restore failure; 2 usage or unknown target.

Deployment-time command

`-capture-appdata-baseline`

Capture the per-user AppData baseline used to seed session pool accounts. Run it after installing an application during server preparation. It does not require the authentication database.

webstream.exe -capture-appdata-baseline [-username <poolAccount>]

Option	Description
`-username <poolAccount>`	Optional pool account to capture from.

webstream.exe -capture-appdata-baseline
webstream.exe -capture-appdata-baseline -username webs01

Related: Phase 2 — Custom Setup · Exit codes: 0 success or baseline already present; 1 on failure.

A worked scripting example

The commands compose into a repeatable provisioning script. The example below builds a complete organization — user, group, app, workspace, policy — and checks the exit code after each step so the script stops on the first failure.

# provision-test-org.ps1
$ws = "C:\WebStream\webstream.exe"

function Invoke-Cli {
  param([string[]] $CliArgs)
  & $ws @CliArgs
  if ($LASTEXITCODE -ne 0) { throw "Command failed ($LASTEXITCODE): $($CliArgs -join ' ')" }
}

Invoke-Cli @("-add-org", "test-org", "Sandbox for CLI testing")
Invoke-Cli @("-init-org-defaults", "test-org")
Invoke-Cli @("-add-user", "test-username", "TestPass123!", "test-user@example.com")
Invoke-Cli @("-add-iam-user", "Test User", "test-org", "test-username")
Invoke-Cli @("-add-group", "test-group", "test-org", "Test group")
Invoke-Cli @("-add-user-to-group", "test-username", "test-group", "test-org")
Invoke-Cli @("-add-app", "test-app", "1.0", "C:\Apps\test-app.exe", "test-org")
Invoke-Cli @("-create-workspace", "test-ws", "AppCollection", "test-org")
Invoke-Cli @("-add-app-to-workspace", "test-app", "1.0", "test-ws", "test-org")
Invoke-Cli @("-grant-workspace", "test-ws", "test-group", "test-org")
Invoke-Cli @("-create-policy", "test_lowtrust", "test-org")
Invoke-Cli @("-assign-policy", "test_lowtrust", "test-ws", "test-org")

Write-Host "test-org provisioned."

Authentication modes

Whether the administration commands are available depends on the organization's authentication mode:

Mode	CLI behaviour
builtin	Full CLI: all authentication and IAM commands work.
workgroup	User management is handled by the external authentication service, not this CLI.
enterprise	Users are managed by the SSO provider; user commands do not apply.
none / disabled	Authentication and IAM commands are refused (exit code 1).

Automation companions

The product CLI is complemented by other automation surfaces:

REST APIs — the IAM and Activity APIs cover the same ground programmatically. See API Reference.
Deployment scripts — PowerShell scripts prepare servers, services, and images during installation.
QA scripts — production QA automation drives provisioning and verification using these same CLI commands.

Note

For the interactive equivalent of these commands, and the recommended order for a first setup, follow Phase 2 — Custom Setup and the Guided Walkthrough.

CLI Scripting Guide

Overview

How to read this guide

Exit codes

Service modes

Authentication commands

-add-user

-remove-user

-list-users

-reset-password

-enable-mfa / -disable-mfa

IAM: Organizations

-add-org

-init-org-defaults

-list-orgs

IAM: Users

-add-iam-user

-delete-iam-user

-list-iam-users

IAM: Groups

-add-group

-list-groups

-add-user-to-group

-list-group-members

IAM: Applications

-add-app

-list-apps

IAM: Workspaces

-create-workspace

-list-workspaces

-add-app-to-workspace

-grant-workspace

IAM: Policies

-create-policy

-list-policies

-assign-policy

Bulk export

-export-iam-config

Import / Export

Database administration

-db-status

-db-backup

-db-restore

Deployment-time command

-capture-appdata-baseline

A worked scripting example

Authentication modes

Automation companions

`-add-user`

`-remove-user`

`-list-users`

`-reset-password`

`-enable-mfa` / `-disable-mfa`

`-add-org`

`-init-org-defaults`

`-list-orgs`

`-add-iam-user`

`-delete-iam-user`

`-list-iam-users`

`-add-group`

`-list-groups`

`-add-user-to-group`

`-list-group-members`

`-add-app`

`-list-apps`

`-create-workspace`

`-list-workspaces`

`-add-app-to-workspace`

`-grant-workspace`

`-create-policy`

`-list-policies`

`-assign-policy`

`-export-iam-config`

`-db-status`

`-db-backup`

`-db-restore`

`-capture-appdata-baseline`