> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# serviceaccount

> cpln serviceaccount — Manage service accounts used for programmatic API access.

Manage service accounts

For a detailed overview, please visit the [service account's](/reference/serviceaccount) reference page.

```none theme={null}
cpln serviceaccount [SUBCOMMAND]
```

```text theme={null}
Commands:
  cpln serviceaccount access-report <ref>  Show the access report for the referenced service account
  cpln serviceaccount add-key <ref>        Add a key to the reference service account
  cpln serviceaccount audit [ref]          Retrieve audit trail events for the referenced service account
  cpln serviceaccount clone <ref>          Create a clone of the referenced service account; this will only duplicate its spec.  [aliases: copy]
  cpln serviceaccount create               Create a new service account
  cpln serviceaccount delete <ref...>      Delete one or more referenced service accounts
  cpln serviceaccount edit <ref>           Edit the referenced service account, as YAML, within an editor
  cpln serviceaccount eventlog <ref>       Show the event log of the referenced service account  [aliases: log]
  cpln serviceaccount get [ref...]         Retrieve one or more referenced service accounts
  cpln serviceaccount patch <ref>          Update the referenced service account's metadata using an input file
  cpln serviceaccount permissions          Show the grantable permissions for a service account object type
  cpln serviceaccount query                Find all the service accounts based on the given query
  cpln serviceaccount remove-key <ref>     Remove a key from the reference service account
  cpln serviceaccount tag <ref...>         Manage the tags belonging to one or more referenced service accounts

Options:
  --help  Show help  [boolean]
```

***

#### serviceaccount access-report

Show the access report for the referenced service account

**Usage**

```none theme={null}
cpln serviceaccount access-report <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount access-report demo-service-account --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+--------------------------------------------------------+--------+
    |PERMISSION |PRINCIPAL                                               |GRANTED |
    |-----------|--------------------------------------------------------|--------|
    |addKey     |/org/demo-cpln-organization/group/superusers            |manage  |
    |addKey     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |create     |/org/demo-cpln-organization/group/superusers            |manage  |
    |create     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |delete     |/org/demo-cpln-organization/group/superusers            |manage  |
    |delete     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |edit       |/org/demo-cpln-organization/group/superusers            |manage  |
    |edit       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |manage     |/org/demo-cpln-organization/group/superusers            |manage  |
    |manage     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |view       |/org/demo-cpln-organization/group/superusers            |manage  |
    |view       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |view       |/org/demo-cpln-organization/group/viewers               |view    |
    +-----------+--------------------------------------------------------+--------+
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount add-key

Add a key to the reference service account

**Usage**

```none theme={null}
cpln serviceaccount add-key <ref> --description KEY_DESCRIPTION [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --description, --desc  Short description for the new key  [required]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <Note>
    The 'key' property returned from the add-key command will only be displayed once. There is no way to retrieve the key in the future.
  </Note>

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount add-key demo-service-account --desc demo-key --org demo-cpln-organization
    ```

    ```text Output theme={null}
    {
      "description": "demo-key",
      "created": "2026-07-03T19:11:33.587Z",
      "key": "s2i02xdNuRppz4KM.ZGVtby1jcGxuLW9yZ2FuaXphdGlvbi5kZW1vLXNlcnZpY2UtYWNjb3VudC5tbVcxSnBEWXo2RTVpbmdUTmhYN2ZRT0VsUzVRU083OXlSWHNjbW1kcGVvPQ.mhMSQyTP7Q761AHOHStEpcAroe07pLpWGjQGc6XUpqU"
    }
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount audit

Retrieve audit trail events for the referenced service account

**Usage**

```none theme={null}
cpln serviceaccount audit [ref] [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.

  Command options:
    --subject  Filter by subject (serviceaccount name or user email)  [string]
    --context  Audit context name (the 'cpln' context displays Control Plane actions)  [string] [default: "cpln"]
    --since    Relative lookback window from now (e.g., 1h, 24h, 7d). Mutually exclusive with --from/--to  [string] [default: "7d"]
    --from     Start time for audit events (ISO 8601 format or relative duration, e.g., 2025-10-23T07:00:00Z, 7d, 1h). Cannot be used with --since  [string]
    --to       End time for audit events (ISO 8601 format or relative duration, e.g., 2025-10-23T07:00:00Z, 1d, 30m)  [string]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

***

#### serviceaccount clone

Create a clone of the referenced service account; this will only duplicate its spec.

**Usage**

```none theme={null}
cpln serviceaccount clone <ref> --name CLONE_NAME [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --name         Set the name for the clone  [required]
    --description  Optional description, defaults to the name if not set
    --tag          Attach tags (e.g., --tag drink=water)

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount clone demo-service-account --name demo-service-account-clone --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+------------------------------+--------+--------+-----+--------------+
    |NAME                       |DESCRIPTION                   |CREATED |ORIGIN  |KEYS |TAGS          |
    |---------------------------|------------------------------|--------|--------|-----|--------------|
    |demo-service-account-clone |Clone of demo-service-account |Now     |default |     |drink="water" |
    +---------------------------+------------------------------+--------+--------+-----+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount create

Create a new service account

**Usage**

```none theme={null}
cpln serviceaccount create --name SERVICE_ACCOUNT_NAME [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Command options:
    --name                 Name of the new secret  [required]
    --description, --desc  Optional description, defaults to the name if not set
    --tag                  Attach tags (e.g., --tag drink=water)

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount create --name demo-service-account --desc demo-service-account --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------+---------------------+--------+--------+-----+--------------+
    |NAME                 |DESCRIPTION          |CREATED |ORIGIN  |KEYS |TAGS          |
    |---------------------|---------------------|--------|--------|-----|--------------|
    |demo-service-account |demo-service-account |Now     |default |     |drink="water" |
    +---------------------+---------------------+--------+--------+-----+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount delete

Delete one or more referenced service accounts

**Usage**

```none theme={null}
cpln serviceaccount delete <ref...> [OPTIONS]
```

<Warning>
  Deleting a service account will remove all associated keys
</Warning>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount delete demo-service-account --org demo-cpln-organization
    ```

    ```text Output theme={null}
    If the delete was successful, a new command prompt will be shown.
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount edit

Edit the referenced service account, as YAML, within an editor

**Usage**

```none theme={null}
cpln serviceaccount edit <ref> [OPTIONS]
```

<Note>
  The default editor can be set by using the EDITOR environment variable.
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --replace, -r  Replace instead of patch/merge  [boolean] [default: false]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount edit demo-service-account --org demo-cpln-organization
    ```

    ```text Output theme={null}
    Your default editor will be launched.

    Once any modifications are saved, the updates will be sent to the API.
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount eventlog

Show the event log of the referenced service account

**Usage**

```none theme={null}
cpln serviceaccount eventlog <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount eventlog demo-service-account --org demo-cpln-organization
    ```

    ```text Output theme={null}
    The event log for the referenced service account will be shown.
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount get

Retrieve one or more referenced service accounts

**Usage**

```none theme={null}
cpln serviceaccount get [ref...] [OPTIONS]
```

<Note>
  An empty reference will return all references
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [default: []]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Get all service accounts

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount get --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+-----------------------------------------+---------------+--------+-----------------+--------------+
    |NAME                       |DESCRIPTION                              |CREATED        |ORIGIN  |KEYS             |TAGS          |
    |---------------------------|-----------------------------------------|---------------|--------|-----------------|--------------|
    |controlplane               |Built-in serviceaccount used by Contr... |5 years ago    |builtin |                 |              |
    |cpln-user                  |cpln-user                                |2 years ago    |default |sOajhentlsc226k8 |              |
    |demo-service-account       |demo-service-account                     |10 minutes ago |default |s2i02xdNuRppz4KM |drink="water" |
    |demo-service-account-get-1 |demo-service-account-get-1               |Now            |default |                 |              |
    |demo-service-account-get-2 |demo-service-account-get-2               |Now            |default |                 |              |
    +---------------------------+-----------------------------------------+---------------+--------+-----------------+--------------+
    ```
  </CodeGroup>

  * Get one service account

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount get demo-service-account-get-1 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+---------------------------+--------+--------+-----+-----+
    |NAME                       |DESCRIPTION                |CREATED |ORIGIN  |KEYS |TAGS |
    |---------------------------|---------------------------|--------|--------|-----|-----|
    |demo-service-account-get-1 |demo-service-account-get-1 |Now     |default |     |     |
    +---------------------------+---------------------------+--------+--------+-----+-----+
    ```
  </CodeGroup>

  * Get multiple service accounts

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount get demo-service-account-get-1 demo-service-account-get-2 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+---------------------------+--------+--------+-----+-----+
    |NAME                       |DESCRIPTION                |CREATED |ORIGIN  |KEYS |TAGS |
    |---------------------------|---------------------------|--------|--------|-----|-----|
    |demo-service-account-get-1 |demo-service-account-get-1 |Now     |default |     |     |
    |demo-service-account-get-2 |demo-service-account-get-2 |Now     |default |     |     |
    +---------------------------+---------------------------+--------+--------+-----+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount patch

Update the referenced service account's metadata using an input file

**Usage**

```none theme={null}
cpln serviceaccount patch <ref> --file FILE_NAME [OPTIONS]
```

<Note>
  Running this command with the option **`--file -`** sets the input to stdin. The input is required to be a valid JSON or YAML string (e.g., `{"description": "My new description"}` or `description: My new description`). To complete the update, press Control-D (or Control-Z if you are using Windows).
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --file, -f  File to load the patch from. Use `--file -` to enable input from stdin.  [required]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount patch demo-service-account --file update.json --org demo-cpln-organization
    ```

    ```text Output theme={null}
    The changes within the JSON file will be performed against the referenced service account.
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount permissions

Show the grantable permissions for a service account object type

**Usage**

```none theme={null}
cpln serviceaccount permissions [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount permissions --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------+---------------------------------------+-------------------------------------------+
    |NAME   |DESCRIPTION                            |IMPLIES                                    |
    |-------|---------------------------------------|-------------------------------------------|
    |addKey |Add key to an existing service account |                                           |
    |create |Create new service accounts            |                                           |
    |delete |Delete service accounts                |                                           |
    |edit   |Modify existing resources              |view                                       |
    |manage |Full access                            |addKey, create, delete, edit, manage, view |
    |view   |Read-only access                       |                                           |
    +-------+---------------------------------------+-------------------------------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount query

Find all the service accounts based on the given query

**Usage**

```none theme={null}
cpln serviceaccount query QUERY_OPTIONS [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Query options:
    --match             Query filter type  [choices: "all", "none", "any"] [default: "all"]
    --property, --prop  Property to query
    --tag               Tag to query
    --rel               Relation to query

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <Note>
    Use the `--match` option to display **all**, **none**, or **any** of the results based on a given property or tag
  </Note>

  * Search for a service account based on the name property

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount query --match any --prop name=demo-service-account --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    |NAME                 |DESCRIPTION          |CREATED        |ORIGIN  |KEYS             |TAGS          |
    |---------------------|---------------------|---------------|--------|-----------------|--------------|
    |demo-service-account |demo-service-account |10 minutes ago |default |s2i02xdNuRppz4KM |drink="water" |
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    ```
  </CodeGroup>

  * Search for a service account based on the description property

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount query --match any --prop description="demo-service-account" --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    |NAME                 |DESCRIPTION          |CREATED        |ORIGIN  |KEYS             |TAGS          |
    |---------------------|---------------------|---------------|--------|-----------------|--------------|
    |demo-service-account |demo-service-account |10 minutes ago |default |s2i02xdNuRppz4KM |drink="water" |
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    ```
  </CodeGroup>

  * Search for a service account based on a tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount query --match any --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    |NAME                 |DESCRIPTION          |CREATED        |ORIGIN  |KEYS             |TAGS          |
    |---------------------|---------------------|---------------|--------|-----------------|--------------|
    |demo-service-account |demo-service-account |10 minutes ago |default |s2i02xdNuRppz4KM |drink="water" |
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    ```
  </CodeGroup>

  * Search for a service account based on a property and tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount query --match any --prop description="demo-service-account" --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    |NAME                 |DESCRIPTION          |CREATED        |ORIGIN  |KEYS             |TAGS          |
    |---------------------|---------------------|---------------|--------|-----------------|--------------|
    |demo-service-account |demo-service-account |10 minutes ago |default |s2i02xdNuRppz4KM |drink="water" |
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount remove-key

Remove a key from the reference service account

**Usage**

```none theme={null}
cpln serviceaccount remove-key <ref> --key KEY_TO_REMOVE [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --key  Name of the key to remove. Can be repeated.  [required]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * For the example below, the created service account key is:

  ```
  +---------------------+---------------------+--------+--------+-----+--------------+
  |NAME                 |DESCRIPTION          |CREATED |ORIGIN  |KEYS |TAGS          |
  |---------------------|---------------------|--------|--------|-----|--------------|
  |demo-service-account |demo-service-account |Now     |default |     |drink="water" |
  +---------------------+---------------------+--------+--------+-----+--------------+
  ```

  * Remove key

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount remove-key demo-service-account --key sASZzPsODwqBITpY --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    |NAME                 |DESCRIPTION          |CREATED        |ORIGIN  |KEYS             |TAGS          |
    |---------------------|---------------------|---------------|--------|-----------------|--------------|
    |demo-service-account |demo-service-account |10 minutes ago |default |s2i02xdNuRppz4KM |drink="water" |
    +---------------------+---------------------+---------------+--------+-----------------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### serviceaccount tag

Manage the tags belonging to one or more referenced service accounts

**Usage**

```none theme={null}
cpln serviceaccount tag <ref...> --tag KEY=VALUE [OPTIONS]
```

<Note>
  Built-in tags, which begin with cpln/\*, can't be modified.
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]

  Command options:
    --tag         Attach tags (e.g., --tag drink=water)
    --remove-tag  Remove tags (e.g., --remove-tag tagname)

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Add a tag to a service account

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount tag demo-service-account-tag-1 --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+---------------------------+--------+--------+-----+--------------+
    |NAME                       |DESCRIPTION                |CREATED |ORIGIN  |KEYS |TAGS          |
    |---------------------------|---------------------------|--------|--------|-----|--------------|
    |demo-service-account-tag-1 |demo-service-account-tag-1 |Now     |default |     |drink="water" |
    +---------------------------+---------------------------+--------+--------+-----+--------------+
    ```
  </CodeGroup>

  * Update same tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount tag demo-service-account-tag-1 --tag drink=coffee --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+---------------------------+--------+--------+-----+---------------+
    |NAME                       |DESCRIPTION                |CREATED |ORIGIN  |KEYS |TAGS           |
    |---------------------------|---------------------------|--------|--------|-----|---------------|
    |demo-service-account-tag-1 |demo-service-account-tag-1 |Now     |default |     |drink="coffee" |
    +---------------------------+---------------------------+--------+--------+-----+---------------+
    ```
  </CodeGroup>

  * Remove tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount tag demo-service-account-tag-1 --remove drink --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+---------------------------+--------+--------+-----+-----+
    |NAME                       |DESCRIPTION                |CREATED |ORIGIN  |KEYS |TAGS |
    |---------------------------|---------------------------|--------|--------|-----|-----|
    |demo-service-account-tag-1 |demo-service-account-tag-1 |Now     |default |     |     |
    +---------------------------+---------------------------+--------+--------+-----+-----+
    ```
  </CodeGroup>

  * Add same tag to multiple service accounts

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount tag demo-service-account-tag-1 demo-service-account-tag-2 --tag multiple-serviceaccounts=true --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+---------------------------+--------+--------+-----+--------------------------------+
    |NAME                       |DESCRIPTION                |CREATED |ORIGIN  |KEYS |TAGS                            |
    |---------------------------|---------------------------|--------|--------|-----|--------------------------------|
    |demo-service-account-tag-1 |demo-service-account-tag-1 |Now     |default |     |multiple-serviceaccounts="true" |
    |demo-service-account-tag-2 |demo-service-account-tag-2 |Now     |default |     |multiple-serviceaccounts="true" |
    +---------------------------+---------------------------+--------+--------+-----+--------------------------------+
    ```
  </CodeGroup>

  * Update same tag on multiple service accounts (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount tag demo-service-account-tag-1 demo-service-account-tag-2 --tag multiple-serviceaccounts=demo-serviceaccount --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+---------------------------+--------+--------+-----+-----------------------------------------------+
    |NAME                       |DESCRIPTION                |CREATED |ORIGIN  |KEYS |TAGS                                           |
    |---------------------------|---------------------------|--------|--------|-----|-----------------------------------------------|
    |demo-service-account-tag-1 |demo-service-account-tag-1 |Now     |default |     |multiple-serviceaccounts="demo-serviceaccount" |
    |demo-service-account-tag-2 |demo-service-account-tag-2 |Now     |default |     |multiple-serviceaccounts="demo-serviceaccount" |
    +---------------------------+---------------------------+--------+--------+-----+-----------------------------------------------+
    ```
  </CodeGroup>

  * Remove same tag from multiple service accounts (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln serviceaccount tag demo-service-account-tag-1 demo-service-account-tag-2 --remove multiple-serviceaccounts --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +---------------------------+---------------------------+--------+--------+-----+-----+
    |NAME                       |DESCRIPTION                |CREATED |ORIGIN  |KEYS |TAGS |
    |---------------------------|---------------------------|--------|--------|-----|-----|
    |demo-service-account-tag-1 |demo-service-account-tag-1 |Now     |default |     |     |
    |demo-service-account-tag-2 |demo-service-account-tag-2 |Now     |default |     |     |
    +---------------------------+---------------------------+--------+--------+-----+-----+
    ```
  </CodeGroup>
</Accordion>

***