cpln user [SUBCOMMAND]
Commands:
cpln user access-report <ref> Show the access report for the referenced user
cpln user audit [ref] Retrieve audit trail events for the referenced user
cpln user delete <ref...> Delete one or more referenced users
cpln user edit <ref> Edit the referenced user, as YAML, within an editor
cpln user eventlog <ref> Show the event log of the referenced user [aliases: log]
cpln user get [ref...] Retrieve one or more referenced users
cpln user invite Invite users to the current or overridden organization
cpln user patch <ref> Update the referenced user's metadata using an input file
cpln user permissions Show the grantable permissions for a user object type
cpln user query Find all the users based on the given query
cpln user tag <ref...> Manage the tags belonging to one or more referenced users
cpln user update <ref> Update properties of the referenced user
Options:
--help Show help [boolean]
user access-report
Show the access report for the referenced user Usagecpln user access-report <ref> [OPTIONS]
Reference
Reference
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]
Example
Example
cpln user access-report test-128@example.com --org demo-cpln-organization
+------------+--------------------------------------------------------+--------+
|PERMISSION |PRINCIPAL |GRANTED |
|------------|--------------------------------------------------------|--------|
|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 |
|impersonate |/org/demo-cpln-organization/group/superusers |manage |
|impersonate |/org/demo-cpln-organization/serviceaccount/controlplane |manage |
|invite |/org/demo-cpln-organization/group/superusers |manage |
|invite |/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/viewers |view |
|view |/org/demo-cpln-organization/group/superusers |manage |
|view |/org/demo-cpln-organization/serviceaccount/controlplane |manage |
+------------+--------------------------------------------------------+--------+
user audit
Retrieve audit trail events for the referenced user Usagecpln user audit [ref] [OPTIONS]
Reference
Reference
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]
user delete
Delete one or more referenced users Usagecpln user delete <ref...> [OPTIONS]
Deleting a user will remove all associated resources (permissions, group memberships, etc.)
Reference
Reference
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]
Example
Example
cpln user delete demo-user@controlplane.com --org demo-cpln-organization
If the delete was successful, a new command prompt will be shown.
user edit
Edit the referenced user, as YAML, within an editor Usagecpln user edit <ref> [OPTIONS]
The default editor can be set by using the EDITOR environment variable.
Reference
Reference
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]
Example
Example
cpln user edit test-128@example.com --org demo-cpln-organization
Your default editor will be launched.
Once any modifications are saved, the updates will be sent to the API.
user eventlog
Show the event log of the referenced user Usagecpln user eventlog <ref> [OPTIONS]
Reference
Reference
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]
Example
Example
cpln user eventlog test-128@example.com --org demo-cpln-organization
The event log for the referenced user will be shown.
user get
Retrieve one or more referenced users Usagecpln user get [ref...] [OPTIONS]
An empty reference will return all references
Reference
Reference
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]
Example
Example
- Get all users
cpln user get --org demo-cpln-organization
+-----------------------------+---------------------+-----------------------+-------------+---------+------------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|-----------------------|-------------|---------|------------------------------------------|
|rMdL2BFDxEeYQPA5qRYGbLivhVS2 |Kyle Cupp |kyle@controlplane.com |2 years ago |firebase |firebase/sign_in_provider="microsoft.com" |
|3mpcnkfyNhYXdjq8TbLefzXwyfu1 |Majid Abu Rmelah |majid@controlplane.com |6 months ago |firebase |firebase/sign_in_provider="microsoft.com" |
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+-----------------------+-------------+---------+------------------------------------------+
- Get one user
cpln user get test-128@example.com --org demo-cpln-organization
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
user invite
Invite users to the current or overridden organization Usagecpln user invite --email EMAIL_ADDRESS [--group GROUP_NAME] [OPTIONS]
Reference
Reference
Command options:
--email Email address of the user to invite [required]
--group Primary group to add the user to after they accept an invitation
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]
Example
Example
cpln user invite --email demo@controlplane.com --org demo-cpln-organization
If the invite request was successful, a JSON output with the task ID will be shown.
user patch
Update the referenced user’s metadata using an input file Usagecpln user patch <ref> --file FILE_NAME [OPTIONS]
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).Reference
Reference
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]
Example
Example
cpln user patch test-128@example.com --file update.json --org demo-cpln-organization
The changes within the JSON file will be performed against the referenced user.
user permissions
Show the grantable permissions for a user object type Usagecpln user permissions [OPTIONS]
Reference
Reference
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]
Example
Example
cpln user permissions --org demo-cpln-organization
+------------+-----------------------------+------------------------------------------------+
|NAME |DESCRIPTION |IMPLIES |
|------------|-----------------------------|------------------------------------------------|
|delete |Delete existing users | |
|edit |Modify existing users |view |
|impersonate |Lets you impersonate a user | |
|invite |Can invite users to this org | |
|manage |Full access |delete, edit, impersonate, invite, manage, view |
|view |Read-only access | |
+------------+-----------------------------+------------------------------------------------+
user query
Find all the users based on the given query Usagecpln user query QUERY_OPTIONS [OPTIONS]
Reference
Reference
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]
Example
Example
Use the
--match option to display all, none, or any of the results based on a given property or tag- Search for a user based on a property
cpln user query --match any --prop email=test-128@example.com --org demo-cpln-organization
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
- Search for a user based on a tag
cpln user query --match any --tag firebase/sign_in_provider="password" --org demo-cpln-organization
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
- Search for a user based on a property and tag
cpln user query --match any --prop email=test-128@example.com --tag firebase/sign_in_provider="password" --org demo-cpln-organization
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
user tag
Manage the tags belonging to one or more referenced users Usagecpln user tag <ref...> --tag KEY=VALUE [OPTIONS]
Built-in tags, which begin with cpln/*, can’t be modified.
Reference
Reference
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]
Example
Example
- Add a tag
cpln user tag test-128@example.com --tag drink=water --org demo-cpln-organization
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |drink="water" |
| | | | | |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
- Update same tag (after running the example above)
cpln user tag test-128@example.com --tag drink=coffee --org demo-cpln-organization
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |drink="coffee" |
| | | | | |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
- Remove tag (after running the example above)
cpln user tag test-128@example.com --remove drink --org demo-cpln-organization
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
user update
Update properties of the referenced user Usagecpln user update <ref> --set UPDATE_PROPERTY [OPTIONS]
Reference
Reference
Positionals:
ref The resource reference. Usually it is the name of the resource. [required]
Update Properties:
--set Update the following properties (e.g., --set description="Updated Description"):
tags.<key> string
--unset Unset a property (same paths as --set, e.g., --unset description)
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]
Options
Options
- The
--setoption allows the modification of the following user properties:- description
- Description of the user
- Type: string
- tags
- Tags (key=value) associated with the user
- Type: string
- description
Example
Example
- For the examples below, the initial user is configured as:
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
- Update a user’s tag
cpln user update test-128@example.com --set tags.user-name="test-128" --org demo-cpln-organization
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+
|ID |FULL NAME |EMAIL |CREATED |IDP |TAGS |
|-----------------------------|---------------------|---------------------|------------|---------|-------------------------------------|
|HkKCu6TcHIMB8ON8iXayuKw5oop2 |test-128@example.com |test-128@example.com |5 years ago |firebase |firebase/sign_in_provider="password" |
| | | | | |user-name="test-128" |
+-----------------------------+---------------------+---------------------+------------+---------+-------------------------------------+