---
title: profile
description: Inspect the current authenticated principal’s profile and update
  your own information.
canonical_url: https://orchestor.io/docs/en/cli/profile
markdown_url: https://orchestor.io/docs/en/cli/profile.md
contentType: reference
---

# profile

`orc profile` retrieves the profile associated with the current credentials and updates a human account’s name, username, image URL, and language preference. Retrieval returns information for the account itself or the machine credentials in use. There is no operation to specify another user’s ID.

Authentication is required. Use [`orc auth login`](https://orchestor.io/docs/cli/auth.md) to configure authentication. API keys can retrieve a profile, but updates require a human account. The personal information managed by `profile` is separate from the CLI credential configuration selected with [`--profile`](https://orchestor.io/docs/cli/global-flags.md).

## Usage

```bash title="terminal"
orc profile get
```

*Retrieve the current authenticated principal’s profile.*

## Fields to update

| Field | Input and behavior |
| --- | --- |
| `name` | A name of 1–255 characters. Leading and trailing whitespace is removed; the value is saved as `firstName` and `lastName` is set to an empty string. Cannot be combined with `firstName` or `lastName`. |
| `firstName` / `lastName` | Strings specifying each part of the name. Leading and trailing whitespace is removed before saving. |
| `username` | 2–32 characters, using letters, numbers, `_`, and `-`. Must be unique across users; clear it with `null`. |
| `profilePictureUrl` | An image URL string, or `null` to clear it. |
| `locale` | `ja`, `en`, or `null` to clear the saved preference. |

This operation cannot change `id`, `email`, `createdAt`, permissions, or Workspace or organization membership. It also does not support password changes. For organization settings, see [`orc organization`](https://orchestor.io/docs/cli/organization.md).

## Subcommands

### `get`

Returns information from `GET /v1/users/me`. For human accounts, the response includes `id`, `email`, saved `firstName`, `lastName`, `username`, `profilePictureUrl`, `locale`, and `createdAt`, along with the current Workspace and effective permissions. For API keys, `principalType` is `api_key`, and the response includes `apiKeyId` and `apiKeyName`. It does not return the key’s secret value. The `email` for machine credentials is a synthetic identifier, not a delivery address, and `locale` and `createdAt` are omitted.

```bash title="terminal"
orc profile get [options]
```

#### Examples

```bash title="terminal"
orc profile get --json
```

*Retrieve the profile as JSON.*

### `update`

Sends updates to `PATCH /v1/users/me`. Read JSON with `--stdin`. Specify at least one field to update; omitted fields are preserved. After an update, the response includes `id`, `email`, `firstName`, `lastName`, `profilePictureUrl`, `username`, and `locale`. Not every field in the retrieval response is included in the update response.

```bash title="terminal"
orc profile update [options]
```

#### Unique options

##### `--first-name`

Body field: firstName

Type: `string`. Optional.

```bash title="terminal"
orc profile update --first-name <value>
```

##### `--last-name`

Body field: lastName

Type: `string`. Optional.

```bash title="terminal"
orc profile update --last-name <value>
```

##### `--locale`

Body field: locale; enum: ja|en; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc profile update --locale <value>
```

##### `--name`

Body field: name; max 255 chars

Type: `string`. Optional.

```bash title="terminal"
orc profile update --name <value>
```

##### `--profile-picture-url`

Profile image URL saved locally; not synchronized to WorkOS.; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc profile update --profile-picture-url <value>
```

##### `--username`

Body field: username; (use "null" or "reset" to clear); max 32 chars

Type: `string`. Optional.

```bash title="terminal"
orc profile update --username <value>
```

#### Examples

```bash title="terminal"
orc profile update --stdin < profile.json
```

*Update your own profile from a file.*

## Examples

### Change your name and language preference

Save this JSON and submit it with `orc profile update --stdin < profile.json`. Check the changes with `orc profile get`.

```json title="profile.json"
{
  "firstName": "Example",
  "lastName": "User",
  "locale": "ja"
}
```

*Change your name and language preference*

### Clear optional settings

`null` clears the username, image URL, and saved language preference. This differs from omitting a field.

```json title="profile.json"
{
  "username": null,
  "profilePictureUrl": null,
  "locale": null
}
```

*Clear optional settings*

## Troubleshooting

### Authentication fails

Check the current authentication state with [`orc auth status`](https://orchestor.io/docs/cli/status.md), and authenticate with [`orc auth login`](https://orchestor.io/docs/cli/auth.md) if needed. If an update returns `A human account is required to update a profile`, authenticate with a human account. This operation cannot change an API key’s display name.

### An update is rejected

Specify at least one field from the table instead of sending empty JSON. Do not combine `name` with `firstName` / `lastName`. Check the username length and allowed characters and the `locale` value. If `This username is already taken` is returned, choose another username.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc profile`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

## Related

- [`orc whoami`](https://orchestor.io/docs/cli/whoami.md): Check the authenticated principal and selected Workspace together.
- [`orc auth status`](https://orchestor.io/docs/cli/status.md): Check credential status.
- [`orc auth login`](https://orchestor.io/docs/cli/auth.md): Configure CLI authentication.
- [Global options](https://orchestor.io/docs/cli/global-flags.md): Check output formats and how to select credential configurations.

---

[Documentation index](https://orchestor.io/docs/llms.txt)