Mastering AWS WorkSpaces Management Through CLI

Published: June 21, 2025
Author: AWS Automation Team

Download CLI Cheat Sheet

Efficiently managing WorkSpaces through AWS CLI unlocks powerful automation capabilities beyond the AWS Console. By mastering CLI commands, administrators can automate provisioning, perform bulk operations, and integrate WorkSpaces management into DevOps workflows. This comprehensive guide covers essential techniques for harnessing the full potential of AWS CLI in your virtual desktop environment.

Key Insight: AWS CLI reduces WorkSpaces management time by 70% for bulk operations and enables complex automations impossible through the GUI.

Terminal showing AWS CLI commands managing WorkSpaces with automation scripts

Setting Up AWS CLI for WorkSpaces Management

Before executing commands, configure your environment:

Install AWS CLI (v2 recommended)

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

Configure CLI credentials

aws configure
AWS Access Key ID [None]: YOUR_ACCESS_KEY
AWS Secret Access Key [None]: YOUR_SECRET_KEY
Default region name [None]: us-east-1
Default output format [None]: json

Required IAM Permissions

Ensure your IAM user has these permissions:

  • workspaces:CreateWorkspaces
  • workspaces:DescribeWorkspaces
  • workspaces:RebootWorkspaces
  • workspaces:RebuildWorkspaces
  • workspaces:TerminateWorkspaces
  • workspaces:ModifyWorkspaceProperties

Essential CLI Commands for Daily Operations

List all WorkSpaces in your account

aws workspaces describe-workspaces

Get detailed information about a specific WorkSpace

aws workspaces describe-workspaces --workspace-ids ws-abcdef1234567890

Reboot a WorkSpace

aws workspaces reboot-workspaces --reboot-workspace-requests WorkspaceId=ws-abcdef1234567890

Rebuild a WorkSpace (restore to original state)

aws workspaces rebuild-workspaces --rebuild-workspace-requests WorkspaceId=ws-abcdef1234567890

Terminate a WorkSpace

aws workspaces terminate-workspaces --terminate-workspace-requests WorkspaceId=ws-abcdef1234567890

Bulk Operations and Automation

Create Multiple WorkSpaces from CSV

Create users.csv file:

username,email,workspace_bundle
jdoe,jdoe@example.com,wsb-bundle123
asmith,asmith@example.com,wsb-bundle456

Bulk creation script:

#!/bin/bash

while IFS=, read -r username email bundle
do
  aws workspaces create-workspaces
    --workspaces DirectoryId=d-1234567890,UserName=$username,
    BundleId=$bundle,WorkspaceProperties="{}",
    Tags=["Key=Email,Value=$email"]
done < users.csv

Stop All WorkSpaces After Hours

#!/bin/bash

# Get all running WorkSpaces
WORKSPACES=$(aws workspaces describe-workspaces --query "Workspaces[?State=='AVAILABLE'].WorkspaceId" --output text)

# Stop each WorkSpace
for ws in $WORKSPACES
do
  aws workspaces stop-workspaces --stop-workspace-requests WorkspaceId=$ws
done

Advanced Management Scenarios

Automated User Provisioning Workflow

Workflow diagram of automated WorkSpaces provisioning using AWS CLI and Lambda

Combine CLI with other AWS services:

  1. Trigger Lambda function on new user in AD
  2. Lambda executes create-workspaces CLI command
  3. Send notification via SNS
  4. Log results to CloudWatch

Modify Multiple WorkSpaces Properties

Change compute type for all DEV WorkSpaces

# Get all DEV WorkSpaces
DEV_WS=$(aws workspaces describe-workspaces
  --query "Workspaces[?Tags[?Key=='Environment' && Value=='DEV'].WorkspaceId"
  --output text)

# Update compute type
for ws in $DEV_WS
do
  aws workspaces modify-workspace-properties
    --workspace-id $ws
    --workspace-properties ComputeTypeName=STANDARD
done

Monitoring and Reporting

Get WorkSpaces connection history

aws workspaces describe-workspaces-connection-status
--workspace-ids ws-abcdef1234567890

Export all WorkSpaces to CSV

aws workspaces describe-workspaces --query "Workspaces[*].[WorkspaceId,UserName,State,ComputerName,BundleId]"
--output text | awk '{print $1","$2","$3","$4","$5}' > workspaces-report.csv

Troubleshooting Common Issues

ErrorSolutionCLI Command
WorkSpace stuck in PENDINGCheck directory service statusaws ds describe-directories
User cannot log inReset password & rebootaws workspaces reboot-workspaces
CLI command timing outIncrease timeout, check IAM permissionsaws configure set cli_read_timeout 60
Workspace not foundVerify region and workspace IDaws workspaces describe-workspaces --region us-east-1

Integration with AWS Services

Enhance CLI workflows with other AWS services:

  • AWS Lambda: Run CLI commands serverless
  • CloudWatch Events: Schedule maintenance tasks
  • SSM Automation: Create runbooks for complex operations
  • AWS Organizations: Manage multiple accounts

Security Best Practices

  • Use IAM roles instead of access keys when possible
  • Rotate credentials every 90 days
  • Restrict CLI access with IAM policies
  • Enable CloudTrail logging for all CLI activity

Conclusion

Mastering WorkSpaces management through AWS CLI transforms how administrators handle virtual desktop environments. By implementing these techniques:

  • Automate repetitive tasks with scripts
  • Perform bulk operations in seconds
  • Integrate WorkSpaces into CI/CD pipelines
  • Create custom monitoring solutions
  • Reduce management overhead by 60-80%

Begin with basic commands and progressively implement automation scripts. For advanced scenarios, combine with automated provisioning systems and CloudWatch monitoring.