# uip is connectors builder init & connector

> Syntax and options for scaffolding, editing, inspecting, and validating a local Integration Service connector — builder init, init preset apply, init header delete, inspect, and validate.

Part of the [`uip is connectors builder`](./uip-is-connectors-builder.md) local-authoring toolchain. This page covers the two verbs that own a connector's on-disk *shell*:

- **`builder init`** — create a new connector, or edit fields on the one that resolves from the current directory. Also owns `init preset apply` (seed a base/pagination configuration bundle) and `init header delete` (remove a global request header).
- **`builder inspect`** / **`builder validate`** — read-only structure summary and CI-gradable pass/fail check set. These sit directly under `builder`, with no `connector` wrapper in the command path.

For scaffolding activities, auth, triggers, or low-level file edits, see the [sibling pages](./uip-is-connectors-builder.md#this-resource-spans-six-pages).

## Concepts

- **Create vs. edit dispatch** — `init` decides its mode by whether a connector resolves from `--connector-dir` (or the current directory, scanning only the current directory itself — **not** subdirectories, unlike other builder commands' fallback resolution). No connector resolves → **create** (requires `--name`, scaffolds a fresh tree and seeds defaults). One resolves → **edit** (only the flags you pass change; everything else on disk is left as-is). If more than one connector directory would match, `init` fails with `Code: "connectorAmbiguous"` rather than guessing — pass `--connector-dir` explicitly.
- **Why `init` won't scan subdirectories** — every other builder command falls back to scanning immediate subdirectories when no connector resolves in the current directory (see [Concepts](./uip-is-connectors-builder.md#concepts) on the parent page). `init` deliberately skips that fallback: scanning would risk resolving a *sibling* connector directory below cwd and silently editing or renaming it instead of creating a new one. Run `init` from inside the connector's own directory, or pass `--connector-dir` to edit one elsewhere.
- **What `init` folds together** — this single command replaces what used to be separate `connector scaffold`, `metadata set`, `global set`, and base/pagination `config preset` surfaces, so the other three authoring verbs (`auth`, `activity`, `trigger`) stay narrow. Long-tail `element.json` / metadata fields not exposed as flags here (`displayOrder`, `extended`, `typeOauth`, `cloneable`, `tags`, …) go through `state patch` on the [Trigger & state](./uip-is-connectors-builder-trigger.md) page instead.
- **Login requirement on create** — creating a connector without `--organization` requires an active login, because the element key (`design-{org}-{slug}`) stamps the organization. This checks the actual login *status*, not just whether an org name happens to be cached locally — an expired or refresh-failed session fails the check even though `uip login status` itself would still report success. Pass `--organization <slug>` explicitly for offline or CI builds.
- **Header create vs. delete asymmetry** — adding or updating a global header is folded into `init --header VendorName=value` (repeatable). Removing one is the separate `init header delete <vendor-name>` — the one header operation `state patch` cannot do, because it can't address a single `element.json` `parameters[]` array item directly.

## Synopsis

```text
uip is connectors builder init [--name <name>] [--connector-dir <path>] [options...]
uip is connectors builder init preset apply --kind <base|pagination> [--override <key=value>]... [--connector-dir <path>] [--force]
uip is connectors builder init header delete <vendor-name> [--connector-dir <path>]
uip is connectors builder inspect [--connector-dir <path>]
uip is connectors builder validate [--connector-dir <path>]
```

## uip is connectors builder init

Create or configure a connector's shell on disk.

:::note
Use this to bootstrap a brand-new connector (`--name`), or to set connector-level fields — name, description, categories, base URL, headers, lifecycle, tier — on one that already exists. To add resources/activities, use `activity create` on the [Activity & hooks](./uip-is-connectors-builder-activity.md) page. To configure authentication beyond the inline `--auth` sugar, use `auth set` on the [Auth](./uip-is-connectors-builder-auth.md) page. To edit a long-tail `element.json` field this command doesn't expose as a flag, use `state patch`.
:::

### Options

| Long | Value | Description |
|---|---|---|
| `--name <name>` | string | Display name, e.g. `'Acme Widgets'`. Required when creating; the element key and default folder are derived from it. |
| `--connector-dir <path>` | path | Connector directory. See [Concepts](#concepts) above for resolution behavior specific to `init`. |
| `--organization <name>` | slug | Organization slug for the element key (`design-{org}-{name}`). Create mode only; defaults to your logged-in org. |
| `--description <text>` | string | One-line connector description. |
| `--categories <csv>` | csv | Comma-separated category list. Matching is case-insensitive; approved values are canonicalized to their approved spelling (e.g. `crm` → `CRM`). An unrecognized category fails fast here rather than later at `validate`. |
| `--activity-color <hex>` | hex | Hex color for the Studio activity UI. |
| `--base-url <url>` | url | Default base URL — sets the `base.url` configuration entry. A templated URL (`https://{environment}/api`) automatically seeds the backing interpolation config entry it needs. |
| `--accept-type <value>` | string | `Accept` header value. |
| `--content-type <value>` | string | `Content-Type` header value. |
| `--header <kv>` | `VendorName=value` | Global request header. Repeatable. |
| `--lifecycle-stage <stage>` | string | Lifecycle stage, e.g. `GA`, `BETA`. |
| `--tier <tier>` | string | Connector tier. |
| `--auth <type>` | string | Configure auth inline (create mode only): any `auth set --auth-type` value (`oauth2`, `customApiKey`, `none`, `jwtOauth`, `firstPartyService`, …). With `oauth2`, `--authorization-url`, `--token-url`, and `--scope` are required. Type-specific flags beyond the ones below need `auth set`. |
| `--authorization-url <url>` | url | OAuth2 login/consent URL. Required with `--auth oauth2`. |
| `--token-url <url>` | url | OAuth2 token endpoint. Required with `--auth oauth2`. |
| `--token-refresh-url <url>` | url | OAuth2 refresh endpoint. Defaults to `--token-url`. |
| `--token-revoke-url <url>` | url | OAuth2 token revoke endpoint. |
| `--scope <scope>` | string | OAuth2 space-delimited scope string. Required with `--auth oauth2`. |
| `--api-key-param-name <name>` | string | `customApiKey` — vendor header or query parameter name. |
| `--api-key-location <where>` | `header` \| `query` | `customApiKey` — where the key is sent. Default `header`. |
| `--api-key-prefix <prefix>` | string | `customApiKey` — literal prefix. |
| `--key-config-name <key>` | string | `customApiKey` — internal config key. Default `custom.api.key`. |
| `--key-config-display-name <name>` | string | `customApiKey` — UI label. Default `API Key`. |
| `--force` | flag | Apply diffs on existing entries instead of erroring. |

### Examples

```bash
# Create a new connector (auth configured later)
uip is connectors builder init --name 'Acme Widgets'
```

```bash
# Create + OAuth2 + base URL in one call
uip is connectors builder init --name 'Acme Widgets' --base-url https://api.acme.com \
  --auth oauth2 --authorization-url https://acme.com/oauth/authorize \
  --token-url https://acme.com/oauth/token --scope 'read write'
```

```bash
# Edit an existing connector — only the passed flags change
uip is connectors builder init --description 'Acme Widgets connector' --categories crm,sales
```

### Data shape (--output json)

```json
{
  "Code": "ConnectorInitialized",
  "Data": {
    "Mode": "created",
    "ElementKey": "design-myorg-acmewidgets",
    "RepoName": "acme-widgets",
    "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets",
    "FilesCreated": ["app/element/element.json", "..."],
    "OrganizationName": "myorg",
    "OrganizationNameSource": "login",
    "HeadersSeeded": [],
    "BaseUrlSet": false,
    "MetadataChanges": [],
    "AuthConfigured": null
  }
}
```

`Mode` is `"created"` or `"edited"`. Edit mode returns a narrower `Data` shape: `Mode`, `ConnectorRoot`, `HeadersChanged`, `MetadataChanges`, `BaseUrlSet` — there's no `FilesCreated`, `OrganizationName`, or `AuthConfigured`, since those only apply to a fresh scaffold.

## uip is connectors builder init preset apply

Apply a canonical bundle of configuration entries: `base` (base URL plus select/nulls/instance keys) or `pagination` (the four pagination keys).

:::note
Use this to seed the base or pagination configuration keys in one call. The event/polling bundle is a separate preset reached through `trigger create --event-kind`, not through this command. To add one bespoke configuration entry instead of a bundle, use `state patch element.json/configuration/<key>`.
:::

### Options

| Long | Value | Description |
|---|---|---|
| `--kind <kind>` | `base` \| `pagination` | Required. Preset to apply. |
| `--override <kv>` | `key=value` | Per-entry `defaultValue` override. Repeatable. |
| `--connector-dir <path>` | path | Connector directory. |
| `--force` | flag | Apply diffs on existing entries instead of erroring. |

### Example

```bash
uip is connectors builder init preset apply --kind pagination
```

### Data shape (--output json)

```json
{
  "Code": "ConfigPresetApplied",
  "Data": {
    "Kind": "pagination",
    "Added": ["pagination.max"],
    "Updated": [],
    "Unchanged": [],
    "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets"
  }
}
```

## uip is connectors builder init header delete

Remove a global request header by vendor name.

:::note
Use this to remove a global header you no longer want sent. To add or update one, use `init --header VendorName=value` — there's no `init header create`; that operation lives on `init` itself.
:::

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<vendor-name>` | yes | Vendor header name to remove. |

### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Connector directory. |

### Example

```bash
uip is connectors builder init header delete X-Tenant
```

### Data shape (--output json)

```json
{
  "Code": "GlobalHeaderRemoved",
  "Data": { "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets", "VendorName": "X-Tenant" }
}
```

## uip is connectors builder inspect

Produce a read-only structured overview of a connector: auth types, configuration, resources (with standard-resource files and hooks), global hooks, events, and metadata.

:::note
Use this to get a quick map of an existing connector before editing it, or to confirm which resources, hooks, and auth types are present. For pass/fail checks instead of a structure summary, use `validate`.
:::

### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Connector directory. |

### Example

```bash
uip is connectors builder inspect --connector-dir ./my-acme-connector
```

### Data shape (--output json)

```json
{
  "Code": "ConnectorInspected",
  "Data": {
    "ConnectorRoot": "/work/my-acme-connector",
    "ElementKey": "design-myorg-acmewidgets",
    "Name": "Acme Widgets",
    "Description": "Acme Widgets connector",
    "AuthTypes": ["oauth2"],
    "ConfigCount": 5,
    "ConfigKeys": ["base.url", "..."],
    "ResourceCount": 12,
    "ResourceSummary": {
      "/auth_validation": { "Methods": ["GET"], "Type": "standard", "StandardResourceFile": "auth_validation.json", "Hooks": [] }
    },
    "GlobalHooks": [],
    "HasEvents": false,
    "EventTypes": [],
    "Categories": ["CRM"],
    "LifecycleStage": "GA",
    "Metadata": { "...": "verbatim element-metadata.json content" }
  }
}
```

`ResourceSummary` is keyed by the resource's actual on-disk path (e.g. `/auth_validation`), and `Metadata` is the verbatim content of `element-metadata.json`. Both are exempt from the CLI's usual PascalCase key normalization — the raw keys are preserved exactly as they appear on disk, so a selector built from this output (e.g. `/auth_validation`, `{sys_id}`) matches the real file path instead of a mangled `/authValidation` / `{sysId}` variant.

## uip is connectors builder validate

Run the full check set over a connector and emit a structured report. Exits non-zero when the connector is invalid, so CI can gate on it.

:::note
Use this to gate a connector in CI before import or release, and to find errors, warnings, and suggestions across `element.json`, standard-resource files, hooks, and metadata. To browse a connector's structure instead of running checks, use `inspect`.
:::

### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Connector directory. |

### Examples

```bash
uip is connectors builder validate
```

```bash
uip is connectors builder validate --connector-dir ./my-acme-connector
```

### Data shape (--output json)

```json
{
  "Code": "ConnectorValidation",
  "Data": {
    "ConnectorRoot": "/work/my-acme-connector",
    "ElementKey": "design-myorg-acmewidgets",
    "Valid": true,
    "Errors": [],
    "Warnings": [],
    "Info": ["Configuration entries: 5"],
    "Summary": "PASS: 0 error(s), 0 warning(s)"
  }
}
```

The report is emitted on both pass and fail — a failing report still returns `Result: "Success"` with `Valid: false` in `Data` (the command itself didn't error), but the process exits with a non-zero exit code so CI can gate on the outcome without parsing the body.

## Related

- [uip is connectors builder](./uip-is-connectors-builder.md) — concepts, and the tenant-lifecycle verbs (`download`/`import`/`publish`/`publish-status`).
- [Auth](./uip-is-connectors-builder-auth.md) — configure the connector's authentication scheme.
- [Activity & hooks](./uip-is-connectors-builder-activity.md) — define what the connector's activities do.
- [Trigger & state](./uip-is-connectors-builder-trigger.md) — event triggers and low-level element-file edits.

## See also

- [Integration Service tool overview](./uip-is.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)