# uip or folders

> `uip or folders` manages Orchestrator folders — the hierarchical containers that scope processes, jobs, assets, queues, and user permissions. Verbs cover listing, creating, moving, editing, and deleting folders, plus a `runtimes` command that reports machine-runtime allocation inside a folder.

`uip or folders` manages Orchestrator folders — the hierarchical containers that scope processes, jobs, assets, queues, and user permissions. Verbs cover listing, creating, moving, editing, and deleting folders, plus a `runtimes` command that reports machine-runtime allocation inside a folder.

## Synopsis

```
uip or folders <verb> [options]
```

## Verbs

| Verb | Purpose |
|---|---|
| `list` | List folders. Default: folders the current user can access; with `--all`, every folder in the tenant. |
| `create` | Create a folder, optionally nested under a parent. |
| `get` | Fetch one folder by key or path. |
| `delete` | Delete a folder by key or path. |
| `move` | Re-parent a folder, or move it to the root. |
| `edit` | Update display name and/or description. |
| `runtimes` | Show runtime allocation (total / connected / available) per runtime type for a folder. |

## uip or folders list

List folders. The default view uses `GetAllForCurrentUser` — folders the caller has access to. With `--all`, the verb switches to the full `Folders` endpoint (Standard and Solution folders in the tenant); with `--type personal`, it switches to the `PersonalWorkspaces` endpoint. Filtering and sorting flags (`--name`, `--path`, `--type`, `--top-level`, `--order-by`) require `--all`.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-a` | `--all` | flag | off | List all folders in the tenant; required to enable the filter and sort flags below. |
| `-n` | `--name` | text | — | Contains-match on display name. Requires `--all`. |
| — | `--path` | path prefix | — | Filter by folder path prefix (for example, `Shared` matches `Shared` and everything below). Requires `--all`. |
| — | `--type` | enum | — | `standard`, `solution`, or `personal`. Requires `--all`. `personal` switches to the personal-workspaces endpoint. |
| — | `--top-level` | flag | off | Only root folders (no parent). Requires `--all`. Not supported with `--type personal`. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | — | OData sort (for example, `Name asc`). Requires `--all`. |
| — | `--login-validity` | minutes | `10` | Minimum minutes before token expiry that triggers a pre-request refresh. |

### Examples

```bash
# Folders the authenticated user can access
uip or folders list

# All tenant folders, filtered and sorted
uip or folders list --all --type standard --name "Prod" --order-by "Name asc"

# Personal workspaces only
uip or folders list --all --type personal
```

### Data shape (--output json)

```json
{
  "Code": "FolderList",
  "Data": [
    {
      "Key": "a1b2c3d4-0000-0000-0000-000000000001",
      "Name": "Shared",
      "Path": "Shared",
      "Description": "",
      "Type": "Standard",
      "ParentKey": ""
    }
  ]
}
```

With `--all`, items also include `FeedType` and `PermissionModel`. With `--type personal`, the payload is `{ Key, Name, OwnerName, OwnerKey, LastLogin }`.

## uip or folders create

Create a folder, optionally nested under a parent. `--parent` accepts either a folder GUID or a path (`Shared`, `Production/EU`).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<name>` | yes | Folder display name. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-d` | `--description` | text | — | Folder description. |
| `-p` | `--parent` | key or path | — | Parent folder by GUID or path. Omit for a root folder. |
| — | `--feed-type` | enum | `Processes` | `Processes`, `Libraries`, `FolderHierarchy`. |
| — | `--permission-model` | enum | `FineGrained` | `FineGrained` or `InheritFromTenant`. |
| — | `--provision-type` | enum | `Automatic` | `Automatic` or `Manual`. |

### Examples

```bash
uip or folders create "Staging"

uip or folders create "EU" --parent "Production" \
    --description "European workloads"

uip or folders create "Libraries" --feed-type Libraries \
    --permission-model InheritFromTenant
```

### Data shape (--output json)

```json
{
  "Code": "FolderCreated",
  "Data": {
    "Name": "Staging",
    "ID": 103,
    "Key": "a1b2c3d4-0000-0000-0000-000000000010",
    "Path": "Shared/Staging",
    "Status": "Created successfully"
  }
}
```

## uip or folders get

Fetch one folder by key or path. The positional argument auto-detects: UUID input is treated as a key, anything else as a path.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<folder-key-or-path>` | yes | Folder GUID or path. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or folders get "Shared"
uip or folders get a1b2c3d4-0000-0000-0000-000000000001
uip or folders get "Shared/Staging" --output-filter 'Data.Key'
```

### Data shape (--output json)

```json
{
  "Code": "FolderGet",
  "Data": {
    "Name": "Shared",
    "ID": 101,
    "Key": "a1b2c3d4-0000-0000-0000-000000000001",
    "Description": "No description",
    "Path": "Shared",
    "ParentID": "Root",
    "FolderType": "Standard",
    "IsPersonal": "No",
    "ProvisionType": "Automatic",
    "PermissionModel": "FineGrained",
    "FeedType": "Processes"
  }
}
```

## uip or folders delete

Delete a folder by key or path. Fails if the folder contains entities or user associations — remove or move contents first.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<folder-key-or-path>` | yes | Folder GUID or path. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or folders delete "Shared/Staging"
uip or folders delete a1b2c3d4-0000-0000-0000-000000000010
uip or folders delete "Shared/Staging" --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "FolderDelete",
  "Data": {
    "Key": "a1b2c3d4-0000-0000-0000-000000000010",
    "Path": "Shared/Staging",
    "Status": "Deleted successfully"
  }
}
```

## uip or folders move

Move a folder to a new parent, or up to the root. You must provide exactly one of `--parent` or `--root`.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<folder-key-or-path>` | yes | Folder GUID or path to move. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-p` | `--parent` | key or path | — | New parent folder. Required unless `--root` is set. |
| — | `--root` | flag | off | Move to the top level (no parent). |

### Examples

```bash
uip or folders move "Shared/Staging" --parent "Production"
uip or folders move a1b2c3d4-0000-0000-0000-000000000010 --root
uip or folders move "Shared/Staging" --parent "Production" \
    --output-filter 'Data.TargetParentPath'
```

### Data shape (--output json)

```json
{
  "Code": "FolderMove",
  "Data": {
    "FolderKey": "a1b2c3d4-0000-0000-0000-000000000010",
    "FolderPath": "Shared/Staging",
    "TargetParentPath": "Production",
    "Status": "Moved successfully"
  }
}
```

`--root` sets `TargetParentPath` to `(root)`.

## uip or folders edit

Update display name and/or description. At least one of `--name` or `--description` must be provided.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<folder-key-or-path>` | yes | Folder GUID or path. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-n` | `--name` | text | — | New display name. |
| `-d` | `--description` | text | — | New description. |

### Examples

```bash
uip or folders edit a1b2c3d4-0000-0000-0000-000000000010 --name "Staging (EU)"
uip or folders edit "Shared/Staging" --description "Pre-prod runs"
uip or folders edit "Shared/Staging" --name "Staging (EU)" --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "FolderUpdate",
  "Data": { "Status": "Updated successfully" }
}
```

## uip or folders runtimes

List runtime allocation for a folder — for each runtime type, how many slots are total, connected, and available. Useful for checking capacity before starting jobs.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<folder-key-or-path>` | yes | Folder GUID or path. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or folders runtimes "Shared"
uip or folders runtimes a1b2c3d4-0000-0000-0000-000000000001
uip or folders runtimes "Shared" \
    --output-filter "Data[?Type=='Unattended'].Available | [0]"
```

### Data shape (--output json)

```json
{
  "Code": "FolderRuntimes",
  "Data": [
    { "Type": "Unattended", "Total": 4, "Connected": 3, "Available": 1 },
    { "Type": "NonProduction", "Total": 2, "Connected": 1, "Available": 1 }
  ]
}
```

## Exit codes

See [Exit codes](./exit-codes.md). No verb-specific overrides.

## Related commands

- [`uip or processes`](./uip-orchestrator-processes.md) — folder-scoped process bindings.
- [`uip or machines`](./uip-orchestrator-machines.md) — especially `machines assign` / `unassign` for folder membership.
- [`uip or users`](./uip-orchestrator-users.md) — `users list-in-folder`, `users assign`, `users unassign`.
- [`uip or roles`](./uip-orchestrator-roles.md) — folder-level role assignments.

## See also

- [Global options](./global-options.md).
- [Sessions](./concepts-sessions.md) — tenant and folder context resolution.