# uip or calendars

> `uip or calendars` manages **calendars** — the tenant-scoped lists of excluded dates (also called "Non-Working Days") that time triggers consult to skip scheduled runs. Each calendar has a name, a timezone, and a list of excluded dates.

`uip or calendars` manages **calendars** — the tenant-scoped lists of excluded dates (also called "Non-Working Days") that time triggers consult to skip scheduled runs. Each calendar has a name, a timezone, and a list of excluded dates.

## Synopsis

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

## Verbs

| Verb | Purpose |
|---|---|
| `list` | List calendars in the tenant. |
| `get` | Fetch one calendar by key, including excluded dates. |
| `create` | Create a calendar with an optional timezone. |
| `update` | Rename or retimezone a calendar by key. |
| `delete` | Delete a calendar by key. |

All verbs honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip or calendars list

List all calendars in the tenant. Returns the summary fields (`id`, `name`, `timeZoneId`, `excludedDates`, `key`). Use `calendars get` for a single calendar.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |

### Examples

```bash
uip or calendars list
uip or calendars list --limit 100
uip or calendars list --output-filter 'Data[].{k:key, n:name}'
```

### Data shape (--output json)

```json
{
  "Code": "CalendarList",
  "Data": [
    {
      "name": "US Holidays",
      "timeZoneId": "America/New_York",
      "excludedDates": ["2025-07-04", "2025-12-25"],
      "key": "a1b2c3d4-0000-0000-0000-000000000001",
      "id": 1001
    }
  ]
}
```

## uip or calendars get

Fetch a calendar by GUID key. Returns full details, including excluded dates.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<calendar-key>` | yes | Calendar key (GUID). Find it with `calendars list`. |

### Options

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

### Examples

```bash
uip or calendars get a1b2c3d4-0000-0000-0000-000000000001
uip or calendars get a1b2c3d4-0000-0000-0000-000000000001 \
    --output-filter 'Data.excludedDates'
```

### Data shape (--output json)

```json
{
  "Code": "CalendarGet",
  "Data": {
    "name": "US Holidays",
    "timeZoneId": "America/New_York",
    "excludedDates": ["2025-07-04", "2025-12-25"],
    "key": "a1b2c3d4-0000-0000-0000-000000000001",
    "id": 1001
  }
}
```

## uip or calendars create

Create a new calendar. Calendars are tenant-scoped. The timezone defaults to UTC if `--time-zone` is omitted.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<name>` | yes | Calendar name. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--time-zone` | tz ID | UTC | Calendar timezone (for example, `Europe/Bucharest`). |

### Examples

```bash
uip or calendars create "EU Holidays" --time-zone "Europe/Bucharest"
uip or calendars create "US Holidays"
```

### Data shape (--output json)

```json
{
  "Code": "CalendarCreated",
  "Data": {
    "name": "EU Holidays",
    "timeZoneId": "Europe/Bucharest",
    "excludedDates": [],
    "key": "a1b2c3d4-0000-0000-0000-000000000010",
    "id": 1010
  }
}
```

:::note
This verb creates the calendar record with an empty `excludedDates` list. Populating excluded dates is not exposed via the CLI — use the Orchestrator UI or API directly.
:::

## uip or calendars update

Update a calendar by GUID key. Only the fields you supply change; the rest are preserved.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<calendar-key>` | yes | Calendar key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--name` | text | unchanged | New name. |
| — | `--time-zone` | tz ID | unchanged | New timezone. |

### Examples

```bash
uip or calendars update a1b2c3d4-0000-0000-0000-000000000010 \
    --name "EU Public Holidays"

uip or calendars update a1b2c3d4-0000-0000-0000-000000000010 \
    --time-zone "Europe/Berlin"
```

### Data shape (--output json)

```json
{
  "Code": "CalendarUpdated",
  "Data": {
    "name": "EU Public Holidays",
    "timeZoneId": "Europe/Bucharest",
    "excludedDates": [],
    "key": "a1b2c3d4-0000-0000-0000-000000000010",
    "id": 1010
  }
}
```

## uip or calendars delete

Delete a calendar by GUID key.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<calendar-key>` | yes | Calendar key (GUID). |

### Options

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

### Examples

```bash
uip or calendars delete a1b2c3d4-0000-0000-0000-000000000010
```

### Data shape (--output json)

```json
{
  "Code": "CalendarDeleted",
  "Data": {
    "Key": "a1b2c3d4-0000-0000-0000-000000000010",
    "Name": "EU Public Holidays",
    "Status": "Deleted successfully"
  }
}
```

## Related commands

- [`uip or settings`](./uip-orchestrator-settings.md) — `settings timezones` lists timezone IDs valid for `--time-zone`.

## See also

- [Global options](./global-options.md) — `--output`, `--output-filter`, `--log-level`, `--log-file`.
- [Exit codes](./exit-codes.md) — standard exit-code contract.