AWS IAM CLI Commands: Manage Users, Roles, and Policies

Simple explanation

IAM controls who can do what inside your AWS account. Every API call to AWS gets checked against IAM policies before it is allowed or denied.

The AWS CLI is a terminal interface that lets you create, inspect, and update IAM resources (users, groups, roles, and policies) without opening the AWS Console. It shines when you need repeatable, scriptable, auditable changes: adding the same role across ten accounts, checking every policy on a role, or generating a credential report to find stale access keys.

For human access and most application workloads, short-lived credentials obtained through role assumption are the safer default. IAM users with permanent access keys still have valid use cases, but they should not be your starting point.

Before you start

• AWS CLI installed and configured. If you have not set it up yet, follow Installing the AWS CLI and then configuring the AWS CLI.
• Correct account and profile. If you manage multiple AWS accounts, always pass —profile your-profile-name or set AWS_PROFILE to avoid running commands against the wrong account.
• CloudShell as an alternative. If you do not want to install anything locally, AWS CloudShell gives you a browser-based terminal with the CLI pre-installed and authenticated.
• IAM management permissions. You need permissions like iam:CreateRole, iam:AttachRolePolicy, iam:ListUsers, and related actions. A dedicated IAM-management role scoped to the actions you need is better than using full admin.
• Never use root credentials for day-to-day work. The root account should be locked behind MFA and used only for account-level tasks that no other principal can perform.
• Prefer role-based or federated access. Where possible, use IAM Identity Center (SSO) or federated access with an identity provider instead of creating standalone IAM users. See IAM Users vs Roles for guidance on which to choose.

How IAM management works from the CLI

IAM has four core resource types, and the CLI gives you commands for all of them:

• Users are identities with permanent credentials (password, access keys). Best reserved for specific integration use cases, not as the default access model.
• Groups are collections of users. Attach policies to a group and every user in that group inherits those permissions. Groups simplify permission management when you do need IAM users.
• Roles are identities with no permanent credentials. A trusted entity (an EC2 instance, a Lambda function, a human using SSO) assumes the role and receives temporary credentials. Roles are the recommended way to grant access in most scenarios.
• Policies are JSON documents that define what actions are allowed or denied on which resources. Managed policies are standalone and reusable — AWS provides pre-built ones and you can write your own. Inline policies are embedded directly on a single user, group, or role. See managed vs customer managed policies.

Roles have two policy dimensions that are easy to confuse:

• Trust policy defines who can assume the role (the “who can open this door?” question).
• Permissions policy defines what the role can do once assumed (the “what can you touch inside the room?” question).

“Attach” means linking a managed policy to a user, group, or role. “Assume” means a principal is temporarily taking on a role’s identity and permissions. For a deeper explanation of how assumption works, see Role Assumption in AWS.

The CLI is effective for both one-off operations (quickly check what policies a role has) and audit workflows (generate a credential report, list all entities with AdministratorAccess). For long-lived infrastructure, version-controlled tools like Terraform are usually a better fit.

When to use this

Good use cases for the CLI

• Auditing IAM resources. List all roles with a specific policy attached, generate credential reports, check for overly broad permissions.
• Scripting repeatable changes. Create the same role structure in multiple accounts, rotate credentials, bulk-update policy attachments.
• Checking policy attachments. Quickly see what policies are attached to a role, user, or group without navigating the console.
• Creating or updating roles for workloads. Set up a Lambda execution role, an EC2 instance role, or a cross-account role.
• Generating credential reports. Find stale access keys, users without MFA, or unused accounts.
• Quick operational fixes. Attach a missing policy, remove an over-permissive attachment, or clean up a test user.

When the CLI is not the best fit

• Broad declarative infrastructure management. If you are defining IAM for an entire application stack across multiple environments, Terraform gives you version control, plan previews, and drift detection.
• Long-term versioned IAM at scale. When dozens of roles and policies need to evolve together, managing them as code in a repository with review workflows is safer than ad-hoc CLI commands.
• First-time exploration. If you are learning what IAM resources exist in an account you have never seen before, the console’s visual layout can be faster for discovery.

Working with IAM users

IAM users have permanent credentials. They are appropriate for specific integration use cases, such as a third-party service that cannot assume a role, but for most human and application access, roles are preferred. If you do need IAM users, organize them into groups and apply least-privilege policies.

List all IAM users

Returns every IAM user in the account with creation date and ARN.

aws iam list-users

For a cleaner view, filter to just usernames and ARNs:

aws iam list-users --query 'Users[*].[UserName,Arn]' --output table

Create a new IAM user

aws iam create-user --user-name alice

Create a console login profile

This gives the user a password for AWS Console access. The —password-reset-required flag forces them to change it on first login.

aws iam create-login-profile \
  --user-name alice \
  --password 'Temp@Password123!' \
  --password-reset-required

Create access keys for a user

Access keys give the user programmatic access. Before creating them, ask whether a role would work instead. See AWS Access Keys Explained and why long-lived access keys are dangerous.

aws iam create-access-key --user-name alice

Delete a user

# 1. Detach managed policies
aws iam detach-user-policy \
  --user-name alice \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

# 2. Remove from groups
aws iam remove-user-from-group \
  --user-name alice \
  --group-name Developers

# 3. Delete access keys
aws iam delete-access-key \
  --user-name alice \
  --access-key-id AKIAIOSFODNN7EXAMPLE

# 4. Delete the user
aws iam delete-user --user-name alice

Working with IAM groups

Groups let you manage permissions for multiple IAM users at once. Instead of attaching policies to each user individually, attach them to a group and add users to it. When someone leaves a team, remove them from the group and the permissions go away instantly.

List all groups

aws iam list-groups --query 'Groups[*].[GroupName,Arn]' --output table

Create a group

aws iam create-group --group-name Developers

Add a user to a group

aws iam add-user-to-group \
  --user-name alice \
  --group-name Developers

List users in a group

aws iam get-group --group-name Developers \
  --query 'Users[*].[UserName]' --output table

Attach a managed policy to a group

Every user in the group inherits this policy immediately.

aws iam attach-group-policy \
  --group-name Developers \
  --policy-arn arn:aws:iam::aws:policy/PowerUserAccess

Detach a policy from a group

aws iam detach-group-policy \
  --group-name Developers \
  --policy-arn arn:aws:iam::aws:policy/PowerUserAccess

List policies attached to a group

aws iam list-attached-group-policies --group-name Developers

Working with IAM roles

Roles are the preferred way to grant access in AWS. They issue temporary credentials through AWS STS, which eliminates the risk of permanent credential leaks. You attach a trust policy (who can assume the role) and one or more permissions policies (what the role can do). For a full explanation, see IAM Roles Explained.

List all roles

aws iam list-roles --query 'Roles[*].[RoleName,Arn]' --output table

Create a role with a trust policy

Write the trust policy to a file first. This example creates a role that AWS Lambda can assume:

cat > trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "lambda.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF

aws iam create-role \
  --role-name MyLambdaExecutionRole \
  --assume-role-policy-document file://trust-policy.json \
  --description "Execution role for order-processing Lambda"

The trust policy controls who can assume the role. This is separate from the permissions policies that control what the role can do. For more on trust policy structure, see IAM Policy Structure.

Get details for a specific role

Returns the role’s ARN, creation date, trust policy, and description.

aws iam get-role --role-name MyLambdaExecutionRole

List policies attached to a role

aws iam list-attached-role-policies --role-name MyLambdaExecutionRole

Attach a managed policy to a role

aws iam attach-role-policy \
  --role-name MyLambdaExecutionRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

Detach a policy from a role

aws iam detach-role-policy \
  --role-name MyLambdaExecutionRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

Delete a role

# 1. Detach all managed policies (repeat for each attached policy)
aws iam detach-role-policy \
  --role-name MyLambdaExecutionRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

# 2. Delete all inline policies (repeat for each)
aws iam delete-role-policy \
  --role-name MyLambdaExecutionRole \
  --policy-name InlineDynamoDBAccess

# 3. Delete the role
aws iam delete-role --role-name MyLambdaExecutionRole

Working with managed policies

Create a customer managed policy

Write the policy document to a file, then create the policy. This example grants read-only access to a specific S3 bucket:

cat > s3-read-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::my-app-bucket",
        "arn:aws:s3:::my-app-bucket/*"
      ]
    }
  ]
}
EOF

aws iam create-policy \
  --policy-name MyAppS3ReadPolicy \
  --policy-document file://s3-read-policy.json

For guidance on writing well-scoped policies, see IAM Policy Structure and Principle of Least Privilege.

List customer managed policies

Use —scope Local to filter out the hundreds of AWS-managed policies and see only your own:

aws iam list-policies --scope Local \
  --query 'Policies[*].[PolicyName,Arn]' --output table

Attach a managed policy to a user

aws iam attach-user-policy \
  --user-name alice \
  --policy-arn arn:aws:iam::123456789012:policy/MyAppS3ReadPolicy

Retrieve the JSON for an existing policy

This is a two-step process because IAM policies can have multiple versions:

# Step 1: get the default version ID
aws iam get-policy \
  --policy-arn arn:aws:iam::123456789012:policy/MyAppS3ReadPolicy

{
  "Policy": {
    "PolicyName": "MyAppS3ReadPolicy",
    "DefaultVersionId": "v1",
    "...": "..."
  }
}

# Step 2: get the actual JSON document using that version ID
aws iam get-policy-version \
  --policy-arn arn:aws:iam::123456789012:policy/MyAppS3ReadPolicy \
  --version-id v1

Create a new policy version and set it as default

Updating a customer managed policy means creating a new version. The —set-as-default flag makes the new version active immediately.

aws iam create-policy-version \
  --policy-arn arn:aws:iam::123456789012:policy/MyAppS3ReadPolicy \
  --policy-document file://updated-policy.json \
  --set-as-default

IAM retains up to 5 policy versions. If you have reached the limit, delete an old version first with aws iam delete-policy-version. For production environments, consider managing policies with Terraform so changes go through version control and code review.

Working with inline policies

Inline policies are embedded directly on a single user, group, or role. They are useful for tightly scoped, one-off permissions that you do not want reused elsewhere. For reusable permissions, prefer managed policies. See managed vs customer managed policies for guidance on when each type fits.

Add an inline policy to a role

aws iam put-role-policy \
  --role-name MyLambdaExecutionRole \
  --policy-name InlineDynamoDBAccess \
  --policy-document file://dynamo-policy.json

List inline policies on a role

This returns only the policy names. Use get-role-policy to retrieve the actual JSON.

aws iam list-role-policies --role-name MyLambdaExecutionRole

Get an inline policy document

aws iam get-role-policy \
  --role-name MyLambdaExecutionRole \
  --policy-name InlineDynamoDBAccess

Delete an inline policy

aws iam delete-role-policy \
  --role-name MyLambdaExecutionRole \
  --policy-name InlineDynamoDBAccess

Inline policies on users and groups

The same pattern applies with different command prefixes:

# Add inline policy to a user
aws iam put-user-policy \
  --user-name alice \
  --policy-name InlineS3Access \
  --policy-document file://s3-policy.json

# List inline policies on a group
aws iam list-group-policies --group-name Developers

# Delete inline policy from a group
aws iam delete-group-policy \
  --group-name Developers \
  --policy-name InlineS3Access

Simulating and auditing permissions

Simulate a principal’s policy

Test whether a specific IAM entity is allowed to perform an action, without actually performing it. This is useful for debugging AccessDenied errors.

aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789012:role/MyLambdaExecutionRole \
  --action-names s3:GetObject \
  --resource-arns arn:aws:s3:::my-app-bucket/data.json

Find all roles with AdministratorAccess attached

aws iam list-entities-for-policy \
  --policy-arn arn:aws:iam::aws:policy/AdministratorAccess

Generate and retrieve the IAM credential report

The credential report is a CSV listing every IAM user, their password and access key status, MFA configuration, and last-used dates. It is the fastest way to find stale credentials.

# Generate the report (may take a few seconds)
aws iam generate-credential-report

# Download and decode it
aws iam get-credential-report \
  --query 'Content' --output text | base64 --decode

Safer credential guidance

The commands on this page include creating IAM users and access keys because those operations are sometimes necessary. But they should not be your default approach.

Preferred access patterns, ranked from safest to riskiest:

1. IAM roles for workloads. EC2 instances, Lambda functions, ECS tasks, and other AWS services should use roles. The service handles credential rotation automatically.
2. IAM Identity Center (SSO) for humans. Federated access through an identity provider gives humans short-lived credentials tied to their corporate identity.
3. Role assumption with STS for cross-account or elevated access. Use aws sts assume-role to get temporary credentials scoped to a specific role. See AWS STS and Temporary Credentials.
4. IAM users with access keys (last resort). Only when the above options are not possible, such as third-party integrations that require static credentials. Rotate keys regularly, enforce MFA, and scope permissions tightly with least-privilege policies.

Quick reference table

AWS CLI vs Console vs Terraform

Each tool has a sweet spot for IAM management. Choosing the right one depends on whether you are exploring, scripting, or building long-lived infrastructure.