> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Reference for cloudx config commands, including live configs, validation, draft edits, publishing, and version history.

# Configuration

The `cloudx config` commands inspect, validate, edit, and publish inventory configuration stored in CloudX.

Available commands:

* `cloudx config show` for the live config, a published version, or a draft
* `cloudx config validate` for local YAML files or remote configs
* `cloudx config edit` for preparing draft changes to apps, ad units, groups, lists, tags, test devices, network mappings, line items, and A/B tests
* `cloudx config publish` for publishing a draft as the live config
* `cloudx config history` for published config history and publish-time diff counts

## `cloudx config show`

Shows a config as YAML by default.

Use this command when you need to review the exact inventory config that CloudX has stored for an account, compare a published version, or inspect a draft before publishing.

### Usage

```bash theme={null}
cloudx config show [flags]
```

### Address Modes

By default, `config show` returns the live config.

Use only one address mode at a time:

| Mode                 | Description                                                                        |
| -------------------- | ---------------------------------------------------------------------------------- |
| No address flag      | Show the live config.                                                              |
| `--id <config-id>`   | Show a specific config row by stable ID. Can address a published version or draft. |
| `--version <number>` | Show a published version number within the account.                                |
| `--draft`            | Show the account draft. If multiple drafts exist, use `--id` instead.              |

### Flags

| Flag              | Required | Default | Description                                                |
| ----------------- | -------- | ------- | ---------------------------------------------------------- |
| `--id`            | No       |         | Stable config row ID.                                      |
| `--version`       | No       |         | Published config version number. Must be greater than `0`. |
| `--draft`         | No       | `false` | Show the current account draft.                            |
| `--with-metadata` | No       | `false` | Include config row metadata in the output.                 |
| `--json`          | No       | `false` | Print structured JSON instead of the default YAML output.  |

Validation rules:

* Use only one of `--id`, `--version`, or `--draft`.
* `--version` must be greater than `0`.

## Output Format

By default, the command prints the config YAML without row metadata:

```bash theme={null}
cloudx config show
```

Use `--json` to print only the raw config data as JSON:

```bash theme={null}
cloudx config show --version 12 --json
```

Use `--with-metadata` when you need fields such as config ID, account ID, kind, version number, created time, creator metadata, YAML, and raw data:

```bash theme={null}
cloudx config show --version 12 --with-metadata
cloudx config show --id cfg_123 --with-metadata --json
```

### Examples

**Show the live config**

```bash theme={null}
cloudx config show
```

**Show a published version**

```bash theme={null}
cloudx config show --version 12
```

**Show a config by ID**

```bash theme={null}
cloudx config show --id cfg_123
```

**Show the draft with metadata**

```bash theme={null}
cloudx config show --draft --with-metadata
```

## `cloudx config validate`

Validates either a local YAML file or a remote config.

Use this command before sending a config for review, after creating a draft with `cloudx config edit`, or when you need JSON validation output for automation.

### Usage

```bash theme={null}
cloudx config validate [file] [flags]
```

### Local And Remote Validation

When you pass a file path, validation runs locally and does not call the API:

```bash theme={null}
cloudx config validate config.yaml
```

When you omit the file path, validation runs against the remote live config by default:

```bash theme={null}
cloudx config validate
```

Use `--id` to validate a specific config row, including a draft created by `config edit`, or `--version` to validate a published version:

```bash theme={null}
cloudx config validate --id draft_123
cloudx config validate --version 12
```

### Flags

| Flag        | Required | Default | Description                                                                     |
| ----------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `file`      | No       |         | Local YAML file to validate. Omit to validate the remote live config.           |
| `--id`      | No       |         | Stable config row ID to validate remotely.                                      |
| `--version` | No       |         | Published config version number to validate remotely. Must be greater than `0`. |
| `--strict`  | No       | `false` | Exit non-zero when validation warnings are present.                             |
| `--json`    | No       | `false` | Print structured JSON instead of human-readable output.                         |

Validation rules:

* Local file validation does not support `--id` or `--version`.
* Remote validation supports only one of `--id` or `--version`.
* `--version` must be greater than `0`.
* Without `--strict`, warnings are shown but do not make the command fail.
* With `--strict`, either errors or warnings make the command exit non-zero.

### Examples

**Validate a local YAML file**

```bash theme={null}
cloudx config validate config.yaml
```

**Fail on warnings**

```bash theme={null}
cloudx config validate config.yaml --strict
```

**Validate the live config**

```bash theme={null}
cloudx config validate
```

**Validate a draft and print JSON**

```bash theme={null}
cloudx config validate --id draft_123 --json
```

**Validate a published version**

```bash theme={null}
cloudx config validate --version 12
```

## `cloudx config edit`

Edits inventory in a config draft.

Most edit commands save a draft and do not publish the config. By default, the CLI creates a draft from the live config. Use `--config-id` to edit an existing draft in place or copy a specific config row into a new draft. Use `cloudx config publish` when the draft is ready to become live.

After each edit, CloudX validates the resulting draft. The default human-readable output includes the draft ID, whether a draft was created or updated, the base config ID, changed paths, and validation counts. If validation finds issues, the output also shows the `cloudx config validate --id <draft-id>` command to inspect details.

API clients can perform the same writes with `POST /api/v1/config/edit`. The endpoint requires `configuration:write`, accepts a typed `operations` array, and uses the account selected by the authenticated API key.

Cascade delete is not exposed in the public CLI or API write surface.

### Commands

| Command                                                                                                      | Description                                                                                                            |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `cloudx config edit create-app` / `update-app` / `delete-app`                                                | Create, patch, or delete an app.                                                                                       |
| `cloudx config edit create-ad-unit` / `update-ad-unit` / `delete-ad-unit`                                    | Create, patch, or delete an ad unit.                                                                                   |
| `cloudx config edit create-ad-unit-group` / `update-ad-unit-group` / `delete-ad-unit-group`                  | Create, replace membership for, or delete an ad unit group.                                                            |
| `cloudx config edit remove-ad-unit-from-group`                                                               | Remove one ad unit from a group.                                                                                       |
| `cloudx config edit create-list` / `update-list` / `delete-list`                                             | Create, patch, or delete targeting lists.                                                                              |
| `cloudx config edit create-tag` / `update-tag` / `delete-tag`                                                | Create, patch, or delete tags.                                                                                         |
| `cloudx config edit upsert-test-device` / `delete-test-device`                                               | Create, patch, or delete app test devices.                                                                             |
| `cloudx config edit upsert-network-mapping` / `delete-network-mapping`                                       | Create, patch, or delete app/ad-unit bidder mappings.                                                                  |
| `cloudx config edit create-ab-test`                                                                          | Create an A/B test draft, with optional country targeting for the test variant.                                        |
| `cloudx config edit update-ab-test` / `start-ab-test` / `end-ab-test` / `promote-ab-test` / `delete-ab-test` | Change an A/B test and publish the resulting config. `update-ab-test` can also replace test-variant country targeting. |
| `cloudx config edit create-line-item`                                                                        | Create a line item in a draft config.                                                                                  |
| `cloudx config edit update-line-item`                                                                        | Patch an existing line item in a draft config.                                                                         |
| `cloudx config edit delete-line-item`                                                                        | Delete a line item from a draft config.                                                                                |

### Shared Flags

| Flag          | Required | Default                 | Description                                                                                               |
| ------------- | -------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
| `--config-id` | No       |                         | Config row ID to edit. Drafts are edited in place; published or live configs are copied into a new draft. |
| `--summary`   | No       | Generated from the edit | Draft label or edit summary.                                                                              |
| `--strict`    | No       | `false`                 | Exit non-zero when validation warnings are present. Validation errors always exit non-zero.               |
| `--json`      | No       | `false`                 | Print structured JSON instead of the default concise output.                                              |

### Apps

Create and patch apps with core store metadata. Optional string fields can be cleared on update by passing an empty string.

```bash theme={null}
cloudx config edit create-app --name "Puzzle Quest" --bundle-id com.example.puzzle --platform iOS --os-category GAMES
cloudx config edit update-app --id app_123 --status INACTIVE
cloudx config edit delete-app --id app_123
```

### Ad Units

Create and patch ad units with decimal USD CPM bid floors. `--app-id`, `--id`, and references in examples below can be stable IDs or resolvable names where supported by the command.

```bash theme={null}
cloudx config edit create-ad-unit --name "Home Banner" --type BANNER --app-id app_123 --bidfloor 0.5 --banner-refresh-rate-ms 30000
cloudx config edit update-ad-unit --id au_123 --bidfloor 1.5
cloudx config edit delete-ad-unit --id au_123
```

### Ad Unit Groups

Group creates and updates require at least one `--ad-unit-id`. Updating a group replaces its membership with the supplied IDs.

```bash theme={null}
cloudx config edit create-ad-unit-group --name "Homepage Banners" --ad-unit-id au_123 --ad-unit-id au_456
cloudx config edit update-ad-unit-group --id aug_123 --name "Homepage Banners" --ad-unit-id au_123
cloudx config edit remove-ad-unit-from-group --ad-unit-group-id aug_123 --ad-unit-id au_456
cloudx config edit delete-ad-unit-group --id aug_123
```

### Lists

Lists support `DOMAIN` and `IAB_CONTENT_CATEGORY`. Pass repeated `--value` flags, or `--empty` when an empty list is intentional. Deletes fail while the list is still referenced by targeting or account blocked-list settings.

```bash theme={null}
cloudx config edit create-list --name "Blocked Domains" --type DOMAIN --value example.com --value ads.example
cloudx config edit update-list --id "Blocked Domains" --empty
cloudx config edit delete-list --id list_123
```

### Tags

Frequency cap fields must be supplied together. Use `--clear-frequency-cap` on update to remove a cap. Deletes fail while the tag is still referenced by a line item.

```bash theme={null}
cloudx config edit create-tag --id vip --name "VIP"
cloudx config edit update-tag --id vip --frequency-cap-max-impressions 5 --frequency-cap-time-window session
cloudx config edit delete-tag --id vip
```

### Test Devices

Test devices are scoped to an app and device advertising identifier. Upsert only changes supplied optional fields on existing devices.

```bash theme={null}
cloudx config edit upsert-test-device --app-id app_123 --device-ifa 00000000-0000-0000-0000-000000000000 --device-name "QA iPhone" --test 2 --debug true
cloudx config edit delete-test-device --app-id app_123 --device-ifa 00000000-0000-0000-0000-000000000000
```

### Network Mappings

Mappings can target exactly one app or ad unit. Use repeated `--field key=value` flags for adapter-specific values; CloudX validates required fields and formats in the draft validation result.

```bash theme={null}
cloudx config edit upsert-network-mapping --app-id app_123 --adapter inmobi --field app_id=app-456 --field account_id=acct-789
cloudx config edit delete-network-mapping --ad-unit-id au_123 --adapter meta
```

### A/B Tests

`create-ab-test` creates a draft. `update-ab-test`, `start-ab-test`, `end-ab-test`, `promote-ab-test`, and `delete-ab-test` publish the resulting config immediately and return the published config ID and version.

Use `--country` on `create-ab-test` or `update-ab-test` to target the test variant to specific countries. The flag accepts ISO 3166-1 alpha-2 or alpha-3 country codes, can be repeated, and also accepts comma-separated values. CloudX stores the resulting config targeting as alpha-3 codes.

```bash theme={null}
cloudx config edit create-ab-test --ad-unit-id au_123 --name "Floor test" --traffic-ratio 0.25 --country US --country GB
cloudx config edit update-ab-test --ad-unit-id au_123 --name "Floor test" --traffic-ratio 0.25 --country USA,GBR
cloudx config edit start-ab-test --ad-unit-id au_123
cloudx config edit end-ab-test --ad-unit-id au_123 --winner test
cloudx config edit promote-ab-test --ad-unit-id au_123
cloudx config edit delete-ab-test --ad-unit-id au_123
```

### Create A Line Item

```bash theme={null}
cloudx config edit create-line-item [flags]
```

Create requires the core line-item fields below:

| Flag                   | Description                                                            |
| ---------------------- | ---------------------------------------------------------------------- |
| `--name <name>`        | Line item name.                                                        |
| `--priority <number>`  | Line item priority from 1 to 12. Lower numbers are evaluated first.    |
| `--bidfloor <usd-cpm>` | Line item floor in decimal USD CPM. For example, `1.5` is `$1.50` CPM. |

Create also requires exactly one target:

| Flag                      | Description              |
| ------------------------- | ------------------------ |
| `--ad-unit-id <id>`       | Target ad unit ID.       |
| `--ad-unit-group-id <id>` | Target ad unit group ID. |

Optional fields:

| Flag                 | Description                                               |
| -------------------- | --------------------------------------------------------- |
| `--status <status>`  | Line item status, such as `draft`, `active`, or `paused`. |
| `--bidder <adapter>` | Bidder adapter to enable. Repeat for multiple bidders.    |

Example:

```bash theme={null}
cloudx config edit create-line-item \
  --name "US Rewarded" \
  --priority 2 \
  --bidfloor 1.5 \
  --ad-unit-id au_123 \
  --bidder meta \
  --bidder unityAds
```

### Update A Line Item

```bash theme={null}
cloudx config edit update-line-item --id <line-item-id> [fields]
```

Update commands are patch-like. Only `--id` is always required; pass at least one patch field to change. Omitted fields keep their current values. Changing the target with `--ad-unit-id` or `--ad-unit-group-id` clears the previous target reference.

Patch fields:

| Flag                      | Description                                                                                   |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| `--id <id>`               | Line item ID. Required.                                                                       |
| `--name <name>`           | Optional. Patch the line item name.                                                           |
| `--priority <number>`     | Optional. Patch the line item priority from 1 to 12.                                          |
| `--bidfloor <usd-cpm>`    | Optional. Patch the line item floor in decimal USD CPM.                                       |
| `--status <status>`       | Optional. Patch the line item status.                                                         |
| `--ad-unit-id <id>`       | Optional. Patch the target ad unit ID and clear any ad unit group target.                     |
| `--ad-unit-group-id <id>` | Optional. Patch the target ad unit group ID and clear any ad unit target.                     |
| `--bidder <adapter>`      | Optional. Replace bidders with the provided bidder adapter list. Repeat for multiple bidders. |
| `--clear-bidders`         | Optional. Clear all bidders from the line item. Cannot be used with `--bidder`.               |

Validation rules:

* Pass at least one patch field in addition to `--id`.
* Use only one of `--ad-unit-id` or `--ad-unit-group-id`.
* Use only one of `--bidder` or `--clear-bidders`.

Examples:

```bash theme={null}
cloudx config edit update-line-item --id li_123 --bidfloor 1.5
cloudx config edit update-line-item --id li_123 --priority 3 --status paused
cloudx config edit update-line-item --id li_123 --clear-bidders
```

### Delete A Line Item

```bash theme={null}
cloudx config edit delete-line-item --id <line-item-id>
```

Only `--id` is required.

Examples:

```bash theme={null}
cloudx config edit delete-line-item --id li_123
cloudx config edit delete-line-item --id li_123 --summary "Remove old rewarded line item"
```

### OpenAPI Operations

`POST /api/v1/config/edit` uses the same operation names as the CLI: `create_app`, `update_app`, `delete_app`, `create_ad_unit`, `update_ad_unit`, `delete_ad_unit`, `create_ad_unit_group`, `update_ad_unit_group`, `delete_ad_unit_group`, `remove_ad_unit_from_group`, `create_list`, `update_list`, `delete_list`, `create_tag`, `update_tag`, `delete_tag`, `upsert_test_device`, `delete_test_device`, `upsert_network_mapping`, `delete_network_mapping`, `create_line_item`, `update_line_item`, `delete_line_item`, `create_ab_test`, `update_ab_test`, `start_ab_test`, `end_ab_test`, `promote_ab_test`, and `delete_ab_test`.

```json theme={null}
{
  "summary": "Raise US rewarded floor",
  "operations": [
    {
      "update_line_item": [
        {
          "id": "li_123",
          "bidfloor": 1.5
        }
      ]
    }
  ]
}
```

## `cloudx config publish`

Publishes a draft config as the live config.

Use this command after editing and validating a draft. CloudX runs the same publish-time validation checks used by the dashboard before the draft becomes live.

### Usage

```bash theme={null}
cloudx config publish --id <draft-id> [flags]
```

### Flags

| Flag              | Required | Default | Description                                                  |
| ----------------- | -------- | ------- | ------------------------------------------------------------ |
| `--id`            | Yes      |         | Draft config row ID to publish as live.                      |
| `--version-label` | No       |         | Optional label for the published config version.             |
| `--json`          | No       | `false` | Print structured JSON instead of the default concise output. |

Validation behavior:

* Validation errors prevent publishing and make the command exit non-zero.
* Warnings are shown after a successful publish but do not make the command fail.
* When warnings remain, the output shows a `cloudx config validate --id <config-id>` command to inspect details.

### Examples

**Publish a draft**

```bash theme={null}
cloudx config publish --id draft_123
```

**Publish with a version label**

```bash theme={null}
cloudx config publish --id draft_123 --version-label "May floor update"
```

**Print the publish response as JSON**

```bash theme={null}
cloudx config publish --id draft_123 --json
```

**Adjust a bid floor and publish**

```bash theme={null}
cloudx config edit update-line-item --id li_123 --bidfloor 1.5 --summary "Raise US rewarded floor"
cloudx config validate --id draft_123
cloudx config publish --id draft_123 --version-label "Raise US rewarded floor"
```

## `cloudx config history`

Lists config history rows as a table by default.

Use this command when you need to review recent config publishes, see who created each row, or check the precomputed publish-time diff counts for additions and deletions.

### Usage

```bash theme={null}
cloudx config history [flags]
```

### Flags

| Flag               | Required | Default | Description                                                                                            |
| ------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `--since`          | No       |         | Only include configs created at or after this time. Supports RFC3339 timestamps or `YYYY-MM-DD` dates. |
| `--author`         | No       |         | Filter by creator user ID, email, or name substring.                                                   |
| `--include-drafts` | No       | `false` | Include config drafts. By default only published versions are returned.                                |
| `--json`           | No       | `false` | Print structured JSON instead of the default table output.                                             |

Validation rules:

* `--since` must be an RFC3339 timestamp or a `YYYY-MM-DD` date.

### Output Format

The default table includes the config ID, version number, kind, created time, author, diff summary, version label, and description.

```bash theme={null}
cloudx config history
```

Diff values are shown as `+additions/-deletions`, using the `diff_additions` and `diff_deletions` values computed when the config was published.

Use `--json` when scripts need the raw response fields:

```bash theme={null}
cloudx config history --since 2026-05-01 --json
```

### Examples

**List published config history**

```bash theme={null}
cloudx config history
```

**List recent config changes**

```bash theme={null}
cloudx config history --since 2026-05-01
```

**Filter by author**

```bash theme={null}
cloudx config history --author alice@example.com
```

**Include drafts**

```bash theme={null}
cloudx config history --include-drafts
```

## Related

* [CloudX CLI Overview](/en/cli)
* [Authentication Commands](/en/cli/authentication)
* [Auction Inspection](/en/cli/auction-inspection)
* [Reporting Commands](/en/cli/reporting)
* [Examples](/en/cli/examples)