osui-ws-cli

osui-ws-cli is a command-line tool for managing IAM Identity Center (IdC) users and groups as workspace collaborators in OpenSearch UI. It resolves user emails and group names to IdC UUIDs automatically, so you never have to look them up manually.

Use it when you need to add or remove collaborators programmatically, or when the workspace collaborators search UI is unable to find your IdC users or groups.

Prerequisites

Python 3.8 or later
AWS credentials configured (environment variables, ~/.aws/credentials, or instance role)
Your IAM role ARN must be added as an application admin — see Required permissions

Install

macOS and Linux

# Download the script
curl -o osui-ws-cli.py https://help.os.aws.dev/scripts/osui-ws-cli.py
 
# Check if dependencies are already available (likely yes if you use AWS CLI tools)
python3 -c "import boto3, requests, requests_aws4auth; print('ready')"
 
# Run directly
python3 osui-ws-cli.py --version

If the dependency check fails, install them:

pip3 install --break-system-packages boto3 requests requests-aws4auth

On macOS with Homebrew Python, pip3 install without --break-system-packages is blocked by PEP 668. The three packages (boto3, requests, requests-aws4auth) are safe to install this way — they do not conflict with Homebrew internals.

For convenience, make it executable and move to your PATH:

chmod +x osui-ws-cli.py
mv osui-ws-cli.py /usr/local/bin/osui-ws-cli
# Then run as:
osui-ws-cli --help

Or run directly with python3 (no install needed):

python3 osui-ws-cli.py --help

Windows

Open Command Prompt or PowerShell:

# Download the script
curl -o osui-ws-cli.py https://help.os.aws.dev/scripts/osui-ws-cli.py
 
# Install dependencies
pip install boto3 requests requests-aws4auth
 
# Verify
python osui-ws-cli.py --version

Tip: On Windows, replace osui-ws-cli with python osui-ws-cli.py in all examples below, or create a osui-ws-cli.bat wrapper for convenience:

@echo off
python "%~dp0osui-ws-cli.py" %*

Required permissions

The CLI needs two things:

1. IAM policy — attach this to the role or user running the CLI:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sso:ListInstances",
        "identitystore:ListUsers",
        "identitystore:ListGroups",
        "identitystore:DescribeUser",
        "identitystore:DescribeGroup"
      ],
      "Resource": "*"
    }
  ]
}

identitystore:DescribeUser and identitystore:DescribeGroup are only needed if you use list --resolve-names. The other actions are sufficient for add, remove, and basic list.

2. Application admin access — add your IAM role ARN to the application's dashboard admin list. Without this, all workspace API calls return 401.

aws opensearch update-application \
  --id <APP_ID> \
  --region <REGION> \
  --app-configs '{
    "key": "opensearchDashboards.dashboardAdmin.users",
    "value": "[\"<YOUR_IAM_ROLE_ARN>\"]"
  }'

You can also do this from the AWS Console: OpenSearch Service → OpenSearch UI (Dashboards) → your application → Application admins → Add admin.

Usage

osui-ws-cli --endpoint URL --region REGION COMMAND [OPTIONS]

Global options

Option	Description
`--endpoint URL`	OpenSearch application endpoint URL (required)
`--region REGION`	AWS region, e.g. `us-west-2` (required)
`--profile NAME`	AWS credentials profile (default: environment/instance role)
`--output table\|json\|text`	Output format (default: `table`)
`--version`	Print version and exit

Commands

`add` — Add collaborators

osui-ws-cli ... add --workspace NAME [--user EMAIL] [--group NAME] [--access-level LEVEL]

Option	Description
`--workspace NAME`	Workspace name (looked up automatically)
`--workspace-id ID`	Workspace ID from URL, e.g. `qFLIUd` (alternative to `--workspace`)
`--user EMAIL`	IdC user by email — repeatable, UUID resolved automatically
`--group NAME`	IdC group by display name — repeatable, UUID resolved automatically
`--user-id UUID`	IdC user UUID directly (skips lookup)
`--group-id UUID`	IdC group UUID directly (skips lookup)
`--access-level`	`admin`, `readwrite`, or `read` (default: `read`)
`--dry-run`	Preview changes without applying them

Access level mapping:

Level	Permissions granted
`admin`	View, edit, manage workspace settings, delete workspace
`readwrite`	View and edit workspace assets
`read`	View workspace assets only

Examples

Add a single user as admin:

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 add \
  --workspace "Production Observability" \
  --user alice@example.com \
  --access-level admin

Add multiple groups at once:

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 add \
  --workspace "Production Observability" \
  --group "Analytics Team" \
  --group "Security Team" \
  --group "Platform Engineers" \
  --access-level readwrite

Mix users and groups in one command:

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 add \
  --workspace "Production Observability" \
  --user alice@example.com \
  --user bob@example.com \
  --group "Analytics Team" \
  --access-level admin

Add using raw UUIDs (skips IdC lookup — useful in automation):

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 add \
  --workspace-id qFLIUd \
  --user-id e8718350-c0e1-70cb-ef1d-5d0d2f35a6e2 \
  --group-id 920554c4-9041-7012-3834-2f72d092149c \
  --access-level admin

Preview changes without applying (dry run):

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 add \
  --workspace "Production Observability" \
  --group "Security Team" \
  --access-level admin \
  --dry-run

`list` — List current collaborators

osui-ws-cli ... list --workspace NAME [--resolve-names]

Option	Description
`--workspace NAME`	Workspace name (looked up automatically)
`--workspace-id ID`	Workspace ID from URL, e.g. `qFLIUd` (alternative to `--workspace`)
`--resolve-names`	Resolve IdC UUIDs to group names / user emails (requires IdC read access)

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 list \
  --workspace "Production Observability"

Resolve display names for each identity (group names and user emails):

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 list \
  --workspace "Production Observability" \
  --resolve-names

Output as JSON (useful for scripting):

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 list \
  --workspace-id qFLIUd \
  --output json

`remove` — Remove collaborators

osui-ws-cli ... remove --workspace NAME [--user EMAIL] [--group NAME]

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 remove \
  --workspace "Production Observability" \
  --user bob@example.com \
  --group "Analytics Team"

Using an AWS profile

If you use named profiles in ~/.aws/config:

osui-ws-cli \
  --endpoint https://<APP_ENDPOINT> \
  --region us-west-2 \
  --profile my-admin-profile \
  add \
  --workspace "Production Observability" \
  --user alice@example.com \
  --access-level admin

Troubleshooting

Error	Cause	Fix
`401 Unauthorized`	IAM role not in application admin list	Add your role ARN via `aws opensearch update-application` — see Required permissions
`User 'x@example.com' not found`	Email not in IdC identity store	Verify the email in AWS Console → IAM Identity Center → Users
`Group 'X' not found`	Group name not in IdC identity store	Check the exact display name in IAM Identity Center → Groups
`No IAM Identity Center instance found`	Wrong region or IdC not enabled	Confirm the IdC region with `aws sso-admin list-instances --region <REGION>`
`Could not connect to endpoint`	Wrong endpoint URL or no network access	Check the URL in the OpenSearch Service console and VPC/firewall settings
Missing dependency error	`boto3`, `requests`, or `requests-aws4auth` not installed	Run `pip3 install boto3 requests requests-aws4auth`
`WARNING: Could not resolve display names`	Missing `identitystore:DescribeUser` / `identitystore:DescribeGroup` permissions, or wrong region	Add the describe actions to your IAM policy — see Required permissions. The table still renders without display names.

IDC Auth Setup — Enable IAM Identity Center on your application
IDC User & Group Management — Manage IdC application assignments with AWS CLI and SDK
Workspace Permissions — Workspace privacy settings and collaborator roles