> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/v1/interfaces/command-line-interface/user.md).

# User commands

The `user` command group manages DataOS® users: creating and deleting user accounts, issuing API keys, assigning tags (including role assignments), and reviewing a user's audit history. A Platform Administrator typically runs these commands to manage who can access a DataOS® instance and what roles they hold.

## Quick reference

| Command                         | Description                  |
| ------------------------------- | ---------------------------- |
| `dataos-ctl user`               | Manage DataOS® Users         |
| `dataos-ctl user apikey create` | Create an apikey for a user  |
| `dataos-ctl user apikey delete` | Delete the apikey for a user |
| `dataos-ctl user apikey get`    | Get the apikey for a user    |
| `dataos-ctl user authorize`     | Authorize a DataOS® User     |
| `dataos-ctl user changes get`   | Get the changes for a user   |
| `dataos-ctl user create`        | Create a DataOS® User        |
| `dataos-ctl user delete`        | Delete a DataOS® User        |
| `dataos-ctl user get`           | Get DataOS® Users            |
| `dataos-ctl user invites get`   | Get DataOS® User Invites     |
| `dataos-ctl user tag add`       | Add tags to a user           |
| `dataos-ctl user tag delete`    | Delete tags from a user      |

{% hint style="info" %}
`user` accepts the alias `users`. Most `get`-style leaf commands in this group also accept the aliases `ls` and `list`.
{% endhint %}

## dataos-ctl user get

Get one user, or every user in the tenant.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user get \
  [--id ${{user-id}}] \
  [--all]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user get --all
```

{% endtab %}
{% endtabs %}

### Flags

| Flag           | Description                                                          | Type    | Required |
| -------------- | -------------------------------------------------------------------- | ------- | -------- |
| `-i`, `--id`   | ID of the user to get. Defaults to the currently authenticated user. | string  | No       |
| `-a`, `--all`  | Get every user in the tenant.                                        | boolean | No       |
| `-h`, `--help` | Display help for this command.                                       | boolean | No       |

### Example

```bash
dataos-ctl user get --all
```

```
     NAME     │        ID          │  TYPE  │        EMAIL          │                   TAGS
──────────────┼────────────────────┼────────┼───────────────────────┼──────────────────────────────────────────
 Jane Doe     │ janedoetenant       │ person │ jane.doe@example.com  │ roles:id:engineering-data-developer,
              │                    │        │                       │ roles:id:user,
              │                    │        │                       │ users:id:janedoetenant
```

Table columns: `NAME`, `ID`, `TYPE` (`person` or `application`), `EMAIL`, and `TAGS`. The `TAGS` column mixes role-assignment tags (`roles:id:<role-name>`) with a self-reference tag (`users:id:<user-id>`). Without `--all` or `--id`, `get` returns only the currently authenticated user.

## dataos-ctl user create

Create a new DataOS® user, optionally provisioning an API key at the same time.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user create \
  --name ${{user-name}} \
  --email ${{user-email}} \
  --type ${{user-type}} \
  [--user_id ${{user-id}}] \
  [--tags ${{tag-1}},${{tag-2}}] \
  [--apikeyName ${{apikey-name}}] \
  [--duration ${{apikey-duration}}]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user create \
  --name "Jane Doe" \
  --email jane.doe@example.com \
  --type person \
  --tags roles:id:user
```

{% endtab %}
{% endtabs %}

### Flags

| Flag               | Description                                                           | Type    | Required |
| ------------------ | --------------------------------------------------------------------- | ------- | -------- |
| `-n`, `--name`     | The user's name.                                                      | string  | Yes      |
| `-e`, `--email`    | The user's email.                                                     | string  | Yes      |
| `-t`, `--type`     | The user type: `person` or `application`.                             | string  | Yes      |
| `-u`, `--user_id`  | An explicit user ID. Auto-derived from the name and email if omitted. | string  | No       |
| `--tags`           | Comma-separated list of tags to assign, such as role tags.            | strings | No       |
| `--apikeyName`     | Name of an API key to create for the new user.                        | string  | No       |
| `-d`, `--duration` | Duration the provisioned API key should live before expiring.         | string  | No       |
| `-h`, `--help`     | Display help for this command.                                        | boolean | No       |

## dataos-ctl user delete

Delete a DataOS® user.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user delete --id ${{user-id}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user delete --id janedoetenant
```

{% endtab %}
{% endtabs %}

### Flags

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-i`, `--id`   | ID of the user to delete.      | string  | Yes      |
| `-h`, `--help` | Display help for this command. | boolean | No       |

{% hint style="danger" %}
`user delete` is irreversible. Confirm the user ID with `dataos-ctl user get` before running it.
{% endhint %}

## dataos-ctl user authorize

Submit an authorization request for a user from a manifest file.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user authorize --requestManifestFile ${{manifest-file-path}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user authorize --requestManifestFile ./authorize-request.yaml
```

{% endtab %}
{% endtabs %}

### Flags

| Flag                          | Description                                      | Type    | Required |
| ----------------------------- | ------------------------------------------------ | ------- | -------- |
| `-f`, `--requestManifestFile` | Path to the authorization request manifest file. | string  | Yes      |
| `-h`, `--help`                | Display help for this command.                   | boolean | No       |

## dataos-ctl user apikey get

Get the API keys belonging to a user.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user apikey get [--id ${{user-id}}] [--name ${{apikey-name}}]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user apikey get
```

{% endtab %}
{% endtabs %}

### Flags

| Flag           | Description                                                   | Type    | Required |
| -------------- | ------------------------------------------------------------- | ------- | -------- |
| `-i`, `--id`   | ID of the user. Defaults to the currently authenticated user. | string  | No       |
| `-n`, `--name` | Name of the API key.                                          | string  | No       |
| `-h`, `--help` | Display help for this command.                                | boolean | No       |

### Example

```bash
dataos-ctl user apikey get
```

```
 TOKEN │ TYPE │ EXPIRATION │ CREATED │ NAME
```

An empty result means the target user has no active, non-expired API keys.

## dataos-ctl user apikey create

Create a new API key for a user.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user apikey create \
  --id ${{user-id}} \
  --name ${{apikey-name}} \
  [--duration ${{duration}}]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user apikey create --id janedoetenant --name ci-pipeline --duration 24h
```

{% endtab %}
{% endtabs %}

### Flags

| Flag               | Description                                       | Type    | Required          |
| ------------------ | ------------------------------------------------- | ------- | ----------------- |
| `-i`, `--id`       | ID of the user to create the API key for.         | string  | Yes               |
| `-n`, `--name`     | Name of the API key.                              | string  | Yes               |
| `-d`, `--duration` | Duration the API key should live before expiring. | string  | No, default `24h` |
| `-h`, `--help`     | Display help for this command.                    | boolean | No                |

## dataos-ctl user apikey delete

Delete an API key belonging to a user.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user apikey delete --name ${{apikey-name}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user apikey delete --name ci-pipeline
```

{% endtab %}
{% endtabs %}

### Flags

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-n`, `--name` | Name of the API key to delete. | string  | Yes      |
| `-h`, `--help` | Display help for this command. | boolean | No       |

{% hint style="danger" %}
Deleting an API key immediately revokes access for anything using it. Confirm the key name with `dataos-ctl user apikey get` first.
{% endhint %}

## dataos-ctl user tag add

Add tags, such as role assignments, to a user.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user tag add --id ${{user-id}} --tags ${{tag-1}},${{tag-2}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user tag add --id janedoetenant --tags roles:id:engineering-data-developer
```

{% endtab %}
{% endtabs %}

### Flags

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-i`, `--id`   | ID of the user.                | string  | Yes      |
| `-t`, `--tags` | Tags to add.                   | strings | Yes      |
| `-h`, `--help` | Display help for this command. | boolean | No       |

## dataos-ctl user tag delete

Remove tags from a user.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user tag delete --id ${{user-id}} --tags ${{tag-1}},${{tag-2}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user tag delete --id janedoetenant --tags roles:id:engineering-data-developer
```

{% endtab %}
{% endtabs %}

### Flags

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-i`, `--id`   | ID of the user.                | string  | Yes      |
| `-t`, `--tags` | Tags to remove.                | strings | Yes      |
| `-h`, `--help` | Display help for this command. | boolean | No       |

## dataos-ctl user changes get

Get the audit history of changes made to a user, such as tag assignments and API key lifecycle events.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl user changes get [--id ${{user-id}}]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl user changes get --id janedoetenant
```

{% endtab %}
{% endtabs %}

### Flags

| Flag           | Description                                                   | Type    | Required |
| -------------- | ------------------------------------------------------------- | ------- | -------- |
| `-i`, `--id`   | ID of the user. Defaults to the currently authenticated user. | string  | No       |
| `-h`, `--help` | Display help for this command.                                | boolean | No       |

### Example

```bash
dataos-ctl user changes get
```

```
      CHANGE ID      │      SUBJECT ID       │     OBJECT ID     │     WHAT     │      CREATED AT      │ OBJECT TYPE │                    DETAILS
─────────────────────┼───────────────────────┼───────────────────┼──────────────┼──────────────────────┼─────────────┼────────────────────────────────────────────────
 change_001          │ dataos-access-manager │ janedoetenant     │ tag:add      │ 2026-07-10T09:54:29Z │ user        │ roles:id:engineering-data-developer
 change_002          │ janedoetenant         │ janedoetenant     │ token:add    │ 2026-07-10T09:51:01Z │ user        │ 'ci-pipeline' apikey was created
```

Columns: `CHANGE ID`, `SUBJECT ID` (who made the change), `OBJECT ID` (the affected user), `WHAT` (change type, such as `user:create`, `tag:add`, `token:add`, `token:delete`), `CREATED AT`, `OBJECT TYPE`, and `DETAILS`.

## dataos-ctl user invites get

Get pending DataOS® user invites for the tenant.

### Syntax

```bash
dataos-ctl user invites get
```

### Flags

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-h`, `--help` | Display help for this command. | boolean | No       |

{% hint style="warning" %}
`user invites get` requires an elevated, admin-tier role. A user without that permission receives a `Forbidden` error rather than an empty result.
{% endhint %}

## Validation rules

* `--type` on `user create` accepts only `person` or `application`.
* `--id` on most subcommands must match a user ID returned by `dataos-ctl user get --all`.
* `--tags` and other repeatable list flags accept a comma-separated list in a single flag value.

## Related commands

* Tenant commands: the tenant context a user belongs to.
* [Resource commands](/references/v1/interfaces/command-line-interface/resource.md): manage the resources a user's roles grant access to.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/v1/interfaces/command-line-interface/user.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.