WorkSpaces examples using Amazon CLI - Amazon Command Line Interface
Actions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.

WorkSpaces examples using Amazon CLI

The following code examples show you how to perform actions and implement common scenarios by using the Amazon Command Line Interface with WorkSpaces.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.

Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use create-tags.

Amazon CLI

To add tags to a WorkSpace

The following create-tags example adds the specified tags to the specified WorkSpace.

aws workspaces create-tags \
    --resource-id ws-dk1xzr417 \
    --tags Key=Department,Value=Finance

This command produces no output.

For more information, see Tag WorkSpaces resources in the Amazon WorkSpaces Administration Guide.

  • For API details, see CreateTags in Amazon CLI Command Reference.

The following code example shows how to use create-workspaces.

Amazon CLI

Example 1: To create an AlwaysOn WorkSpace

The following create-workspaces example creates an AlwaysOn WorkSpace for the specified user, using the specified directory and bundle.

aws workspaces create-workspaces \
    --workspaces DirectoryId=d-926722edaf,UserName=Mateo,BundleId=wsb-0zsvgp8fc

Output:

{
    "FailedRequests": [],
    "PendingRequests": [
        {
            "WorkspaceId": "ws-kcqms853t",
            "DirectoryId": "d-926722edaf",
            "UserName": "Mateo",
            "State": "PENDING",
            "BundleId": "wsb-0zsvgp8fc"
        }
    ]
}

Example 2: To create an AutoStop WorkSpace

The following create-workspaces example creates an AutoStop WorkSpace for the specified user, using the specified directory and bundle.

aws workspaces create-workspaces \
    --workspaces DirectoryId=d-926722edaf,UserName=Mary,BundleId=wsb-0zsvgp8fc,WorkspaceProperties={RunningMode=AUTO_STOP}

Output:

{
    "FailedRequests": [],
    "PendingRequests": [
        {
            "WorkspaceId": "ws-dk1xzr417",
            "DirectoryId": "d-926722edaf",
            "UserName": "Mary",
            "State": "PENDING",
            "BundleId": "wsb-0zsvgp8fc"
        }
    ]
}

Example 3: To create a user-decoupled WorkSpace

The following create-workspaces example creates a user-decoupled WorkSpace by setting the username to [UNDEFINED], and specifying a WorkSpace name, directory ID, and bundle ID.

aws workspaces create-workspaces \
    --workspaces DirectoryId=d-926722edaf,UserName='"[UNDEFINED]"',WorkspaceName=MaryWorkspace1,BundleId=wsb-0zsvgp8fc,WorkspaceProperties={RunningMode=ALWAYS_ON}

Output:

{
    "FailedRequests": [],
    "PendingRequests": [
        {
            "WorkspaceId": "ws-abcd1234",
            "DirectoryId": "d-926722edaf",
            "UserName": "[UNDEFINED]",
            "State": "PENDING",
            "BundleId": "wsb-0zsvgp8fc",
            "WorkspaceName": "MaryWorkspace1"
        }
    ]
}

For more information, see Launch a virtual desktop in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use delete-tags.

Amazon CLI

To delete a tag from a WorkSpace

The following delete-tags example deletes the specified tag from the specified WorkSpace.

aws workspaces delete-tags \
    --resource-id ws-dk1xzr417 \
    --tag-keys Department

This command produces no output.

For more information, see Tag WorkSpaces resources in the Amazon WorkSpaces Administration Guide.

  • For API details, see DeleteTags in Amazon CLI Command Reference.

The following code example shows how to use deregister-workspace-directory.

Amazon CLI

To deregister a directory

The following deregister-workspace-directory example deregisters the specified directory.

aws workspaces deregister-workspace-directory \
    --directory-id d-926722edaf

This command produces no output.

For more information, see Register a directory with WorkSpaces in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use describe-tags.

Amazon CLI

To describe the tags for a WorkSpace

The following describe-tags example describes the tags for the specified WorkSpace.

aws workspaces describe-tags \
    --resource-id ws-dk1xzr417

Output:

{
    "TagList": [
        {
            "Key": "Department",
            "Value": "Finance"
        }
    ]
}

For more information, see Tag WorkSpaces resources in the Amazon WorkSpaces Administration Guide.

  • For API details, see DescribeTags in Amazon CLI Command Reference.

The following code example shows how to use describe-workspace-bundles.

Amazon CLI

To list the bundles provided by Amazon

The following describe-workspace-bundles example lists the names and IDs of the bundles provided by Amazon, in table format and sorted by name.

aws workspaces describe-workspace-bundles \
    --owner AMAZON \
    --query "Bundles[*].[Name, BundleId]"

Output:

[
    [
        "Standard with Amazon Linux 2",
        "wsb-clj85qzj1"
    ],
    [
        "Performance with Windows 10 (Server 2016 based)",
        "wsb-gm4d5tx2v"
    ],
    [
        "PowerPro with Windows 7",
        "wsb-1pzkp0bx4"
    ],
    [
        "Power with Amazon Linux 2",
        "wsb-2bs6k5lgn"
    ],
    [
        "Graphics with Windows 10 (Server 2019 based)",
        "wsb-03gyjnfyy"
    ],
    ...
]

For more information, see WorkSpaces bundles and images in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use describe-workspace-directories.

Amazon CLI

To describe a registered directory

The following describe-workspace-directories example describes the specified registered directory.

aws workspaces describe-workspace-directories \
    --directory-ids d-926722edaf

Output:

{
    "Directories": [
        {
            "DirectoryId": "d-926722edaf",
            "Alias": "d-926722edaf",
            "DirectoryName": "example.com",
            "RegistrationCode": "WSpdx+9RJ8JT",
            "SubnetIds": [
                "subnet-9d19c4c6",
                "subnet-500d5819"
            ],
            "DnsIpAddresses": [
                "172.16.1.140",
                "172.16.0.30"
            ],
            "CustomerUserName": "Administrator",
            "IamRoleId": "arn:aws:iam::123456789012:role/workspaces_DefaultRole",
            "DirectoryType": "SIMPLE_AD",
            "WorkspaceSecurityGroupId": "sg-0d89e927e5645d7c5",
            "State": "REGISTERED",
            "WorkspaceCreationProperties": {
                "EnableInternetAccess": false,
                "UserEnabledAsLocalAdministrator": true,
                "EnableMaintenanceMode": true
            },
            "WorkspaceAccessProperties": {
                "DeviceTypeWindows": "ALLOW",
                "DeviceTypeOsx": "ALLOW",
                "DeviceTypeWeb": "DENY",
                "DeviceTypeIos": "ALLOW",
                "DeviceTypeAndroid": "ALLOW",
                "DeviceTypeChromeOs": "ALLOW",
                "DeviceTypeZeroClient": "ALLOW",
                "DeviceTypeLinux": "DENY"
            },
            "Tenancy": "SHARED",
            "SelfservicePermissions": {
                "RestartWorkspace": "ENABLED",
                "IncreaseVolumeSize": "DISABLED",
                "ChangeComputeType": "DISABLED",
                "SwitchRunningMode": "DISABLED",
                "RebuildWorkspace": "DISABLED"
            }
        }
    ]
}

For more information, see Manage directories for WorkSpaces Personal in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use describe-workspaces-connection-status.

Amazon CLI

To describe the connection status of a WorkSpace

The following describe-workspaces-connection-status example describes the connection status of the specified WorkSpace.

aws workspaces describe-workspaces-connection-status \
    --workspace-ids ws-dk1xzr417

Output:

{
    "WorkspacesConnectionStatus": [
        {
            "WorkspaceId": "ws-dk1xzr417",
            "ConnectionState": "CONNECTED",
            "ConnectionStateCheckTimestamp": 1662526214.744
        }
    ]
}

For more information, see Administer your WorkSpaces in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use describe-workspaces.

Amazon CLI

To describe a WorkSpace

The following describe-workspaces example describes the specified WorkSpace.

aws workspaces describe-workspaces \
    --workspace-ids ws-dk1xzr417

Output:

{
    "Workspaces": [
        {
            "WorkspaceId": "ws-dk1xzr417",
            "DirectoryId": "d-926722edaf",
            "UserName": "Mary",
            "IpAddress": "172.16.0.175",
            "State": "STOPPED",
            "BundleId": "wsb-0zsvgp8fc",
            "SubnetId": "subnet-500d5819",
            "ComputerName": "WSAMZN-RBSLTTD9",
            "WorkspaceProperties": {
                "RunningMode": "AUTO_STOP",
                "RunningModeAutoStopTimeoutInMinutes": 60,
                "RootVolumeSizeGib": 80,
                "UserVolumeSizeGib": 10,
                "ComputeTypeName": "VALUE"
            },
            "ModificationStates": []
        }
    ]
}

For more information, see Administer your WorkSpaces in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use migrate-workspace.

Amazon CLI

To migrate a WorkSpace

The following migrate-workspace example migrates the specified WorkSpace to the specified bundle.

aws workspaces migrate-workspace \
    --source-workspace-id ws-dk1xzr417 \
    --bundle-id wsb-j4dky1gs4

Output:

{
    "SourceWorkspaceId": "ws-dk1xzr417",
    "TargetWorkspaceId": "ws-x5h1lbkp5"
}

For more information, see Migrate a WorkSpace in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use modify-workspace-creation-properties.

Amazon CLI

To modify a WorkSpace creation property of a directory

The following modify-workspace-creation-properties example enables the EnableInternetAccess property for the specified directory. This enables automatic assignment of public IP addresses for the WorkSpaces created for the directory.

aws workspaces modify-workspace-creation-properties \
    --resource-id d-926722edaf \
    --workspace-creation-properties EnableInternetAccess=true

This command produces no output.

For more information, see Update directory details for your WorkSpaces in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use modify-workspace-properties.

Amazon CLI

To modify the running mode of a WorkSpace

The following modify-workspace-properties example sets the running mode of the specified WorkSpace to AUTO_STOP.

aws workspaces modify-workspace-properties \
    --workspace-id ws-dk1xzr417 \
    --workspace-properties RunningMode=AUTO_STOP

This command produces no output.

For more information, see Modify a WorkSpace in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use modify-workspace-state.

Amazon CLI

To modify the state of a WorkSpace

The following modify-workspace-state example sets the state of the specified WorkSpace to ADMIN_MAINTENANCE.

aws workspaces modify-workspace-state \
    --workspace-id ws-dk1xzr417 \
    --workspace-state ADMIN_MAINTENANCE

This command produces no output.

For more information, see WorkSpace maintenance in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use reboot-workspaces.

Amazon CLI

To reboot a WorkSpace

The following reboot-workspaces example reboots the specified WorkSpace.

aws workspaces reboot-workspaces \
    --reboot-workspace-requests ws-dk1xzr417

Output:

{
    "FailedRequests": []
}

For more information, see Reboot a WorkSpace in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use rebuild-workspaces.

Amazon CLI

To rebuild a WorkSpace

The following rebuild-workspaces example rebuilds the specified WorkSpace.

aws workspaces rebuild-workspaces \
    --rebuild-workspace-requests ws-dk1xzr417

Output:

{
    "FailedRequests": []
}

For more information, see Rebuild a WorkSpace in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use register-workspace-directory.

Amazon CLI

To register a directory

The following register-workspace-directory example registers the specified directory for use with Amazon WorkSpaces.

aws workspaces register-workspace-directory \
    --directory-id d-926722edaf

This command produces no output.

For more information, see Register an existing Amazon Directory Service directory with WorkSpaces Personal in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use restore-workspace.

Amazon CLI

To restore a WorkSpace

The following restore-workspace example restores the specified WorkSpace.

aws workspaces restore-workspace \
    --workspace-id ws-dk1xzr417

This command produces no output.

For more information, see Restore a WorkSpace in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use start-workspaces.

Amazon CLI

To start an AutoStop WorkSpace

The following start-workspaces example starts the specified WorkSpace. The WorkSpace must have a running mode of AutoStop.

aws workspaces start-workspaces \
    --start-workspace-requests WorkspaceId=ws-dk1xzr417

Output:

{
    "FailedRequests": []
}

For more information, see Stop and start an AutoStop WorkSpace in the Amazon WorkSpaces Administration Guide.

The following code example shows how to use stop-workspaces.

Amazon CLI

To stop an AutoStop WorkSpace

The following stop-workspaces example stops the specified WorkSpace. The WorkSpace must have a running mode of AutoStop.

aws workspaces stop-workspaces \
    --stop-workspace-requests WorkspaceId=ws-dk1xzr417

Output:

{
    "FailedRequests": []
}

For more information, see Stop and start an AutoStop WorkSpace in the Amazon WorkSpaces Administration Guide.

  • For API details, see StopWorkspaces in Amazon CLI Command Reference.

The following code example shows how to use terminate-workspaces.

Amazon CLI

To terminate a WorkSpace

The following terminate-workspaces example terminates the specified workspace.

aws workspaces terminate-workspaces \
    --terminate-workspace-requests ws-dk1xzr417

Output:

{
    "FailedRequests": []
}

For more information, see Delete a WorkSpace in the Amazon WorkSpaces Administration Guide.