---
title: stack es security put-role cli command
description: Create or update roles. Behaviour flags: --dry-run — validate all inputs and exit without performing any action 
url: https://docs-v3-preview.elastic.dev/elastic/cli/pull/525/cli/stack/es/security/put-role
---

# stack es security put-role cli command
<cli-modifiers>
</cli-modifiers>

```bash
elastic stack es security put-role --name <name> [options]
```

Create or update roles.
**Behaviour flags:**
`--dry-run` — validate all inputs and exit without performing any action

## Options

<definitions>
  <definition term="--name string required">
    The name of the role that is being created or updated. On Elasticsearch Serverless, the role name must begin with a letter or digit and can only contain letters, digits and the characters '_', '-', and '.'. Each role must have a unique name, as this will serve as the identifier for that role.
  </definition>
  <definition term="--refresh enum">
    If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes.
    **Values:** true, false, wait_for
  </definition>
  <definition term="--applications string[]">
    A list of application privilege entries.
  </definition>
  <definition term="--cluster string[]">
    A list of cluster privileges. These privileges define the cluster-level actions for users with this role.
  </definition>
  <definition term="--global string">
    An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.
  </definition>
  <definition term="--indices string[]">
    A list of indices permissions entries.
  </definition>
  <definition term="--remote-indices string[]">
    A list of remote indices permissions entries. NOTE: Remote indices are effective for remote clusters configured with the API key based model.
    They have no effect for remote clusters configured with the certificate based model.
  </definition>
  <definition term="--remote-cluster string[]">
    A list of remote cluster permissions entries.
  </definition>
  <definition term="--metadata string">
    Optional metadata. Within the metadata object, keys that begin with an underscore (`_`) are reserved for system use.
  </definition>
  <definition term="--run-as string[]">
    A list of users that the owners of this role can impersonate. *Note*: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected.
  </definition>
  <definition term="--description string">
    Optional description of the role descriptor
  </definition>
  <definition term="--transient-metadata string">
    Indicates roles that might be incompatible with the current cluster license, specifically roles with document and field level security. When the cluster license doesn’t allow certain features for a given role, this parameter is updated dynamically to list the incompatible features. If `enabled` is `false`, the role is ignored, but is still listed in the response from the authenticate API.
  </definition>
  <definition term="--[no-]error-trace">
    When set to `true` Elasticsearch will include the full stack trace of errors
    when they occur.
  </definition>
  <definition term="--filter-path string">
    Comma-separated list of filters in dot notation which reduce the response
    returned by Elasticsearch.
    **Repeatable:** pass `--filter-path` multiple times to supply more than one value
  </definition>
  <definition term="--[no-]human">
    When set to `true` will return statistics in a format suitable for humans.
    For example `"exists_time": "1h"` for humans and
    `"exists_time_in_millis": 3600000` for computers. When disabled the human
    readable values will be omitted. This makes sense for responses being consumed
    only by machines.
  </definition>
  <definition term="--[no-]pretty">
    If set to `true` the returned JSON will be "pretty-formatted". Only use
    this option for debugging only.
  </definition>
  <definition term="--input-file string">
    path to a JSON file to use as command input
  </definition>
  <definition term="--[no-]dry-run">
    validate all inputs and exit without performing any action (preview changes without applying them)
  </definition>
</definitions>


## Global Options

<definitions>
  <definition term="--[no-]json">
    output as JSON
  </definition>
</definitions>