# uip is connectors builder

> Syntax and options for the Integration Service connector-authoring and lifecycle commands — download, import, publish, and the local `connectors builder` toolchain.

Integration Service connectors can be authored locally and pushed to a tenant. Two command layers cover this:

- **Tenant lifecycle** — `uip is connectors download`, `import`, `publish`, `publish-status`. Registered directly under `connectors` (not under `builder`), because they talk to a tenant and operate on design/authored connectors rather than the local file tree. Documented on this page.
- **Local authoring** — `uip is connectors builder ...`. Works entirely on a local connector directory (no tenant call, except `builder auth`'s optional live-test) to scaffold, edit, and validate a connector's files before importing them. Split across five pages by domain — see [This resource spans six pages](#this-resource-spans-six-pages) below.

Neither layer touches the read-only catalog covered by [`uip is connectors`](./uip-is-connectors.md) (`list`, `get`, `metadata`, `swagger`, `event-operations`, `audit-logs`, `export`) — that page is about *discovering* connectors already in the catalog; this one is about *authoring* a new one or a new version of one you own.

## This resource spans six pages

- **This page** — concepts, and the tenant-lifecycle verbs: `download`, `import`, `publish`, `publish-status`.
- [Init & connector](./uip-is-connectors-builder-init.md) — `builder init` (scaffold a new connector), `builder connector inspect`/`validate`.
- [Auth](./uip-is-connectors-builder-auth.md) — `builder auth set`/`get`/`system create`/`list`, the connector's authentication scheme.
- [Activity](./uip-is-connectors-builder-activity.md) — `builder activity` CRUD plus its `field`, `method`, and `param` sub-groups — the largest domain, defining what the connector's activities actually do.
- [Activity hooks](./uip-is-connectors-builder-activity-hooks.md) — `builder activity hook` — JavaScript pre/post-request transforms, split out on its own page for the runtime-context reference it needs.
- [Trigger & state](./uip-is-connectors-builder-trigger.md) — `builder trigger create`, `builder state query`/`patch` — event-driven triggers and low-level element-file edits.

## Concepts

- **Connector directory** — a local folder containing `app/element/element.json` (and sibling files for activities, auth, triggers). Almost every command accepts `--connector-dir <path>` to point at one explicitly. When omitted, resolution walks up from the current directory looking for that file; if none is found, it scans immediate subdirectories for a single connector; if still not found, it falls back to the connector recorded by the last `builder init` run in this location (`.uip-connector.json`). If resolution finds more than one candidate, the command fails with `Code: "connectorAmbiguous"` and lists the candidates — pass `--connector-dir` explicitly to disambiguate.
- **Design vs. published connector** — a connector under active local development is a *design* connector (key prefixed `design-...`, private to its author). `publish` promotes it to a tenant-wide *CUSTOM* connector visible to everyone. `download`/`import`/`publish`/`publish-status` all operate on this tenant-side design/published state; the `builder` verbs below operate purely on local files.
- **Discovery** — every `builder` command group ships a `uipath-connector-builder` skill (see [`uip skills`](./uip-skills.md)) that's auto-surfaced to AI coding agents, plus a `--help` block on most commands with explicit "USE WHEN" / "NEVER USE FOR" guidance — read a command's own `--help` output before assuming its scope from the name alone.
- **Typical flow** (per the CLI's own `builder --help` text): `builder init` → `builder auth set` → `builder activity create` → optionally `builder activity hook create` → optionally `builder trigger create` → `builder connector validate` → `uip is connectors import` → `uip is connectors publish`.

## Synopsis

```text
uip is connectors download <connector-key> [--connector-dir <path>] [--tenant <name>]
uip is connectors import [--connector-dir <path>] [--tenant <name>]
uip is connectors publish [--connector-dir <path>] [--version <semver>] [--connector-id <id>] [--wait [--timeout-seconds <n>]] [--tenant <name>]
uip is connectors publish-status <publish-id> [--tenant <name>]
```

`--tenant` is a normal, visible option on the four lifecycle verbs.

## uip is connectors download

Download a design connector's editable source tree by key and unpack it locally for editing.

:::note
Use this to pull a design connector down for local editing, or to bootstrap a working copy of a connector you previously imported/published. To read a connector's record instead, use [`connectors get`](./uip-is-connectors.md#uip-is-connectors-get). To search by name, use [`connectors list --filter`](./uip-is-connectors.md#uip-is-connectors-list). To export a published element's package zip, use [`connectors export`](./uip-is-connectors.md#uip-is-connectors-export) — a different operation from this one.
:::

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<connector-key>` | yes | Exact design connector key, for example `design-myorg-acmewidgets`. |

### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Target directory for the unpacked source. Defaults to the current directory. |
| `--tenant <name>` | name | Override the tenant for the API calls. |

### Example

```bash
uip is connectors download design-myorg-acmewidgets --connector-dir ./pulled
```

### Data shape (--output json)

```json
{
  "Code": "ConnectorDownloaded",
  "Data": {
    "Id": 123,
    "Key": "design-myorg-acmewidgets",
    "ConnectorRoot": "/work/pulled/periodic-design-myorg-acmewidgets"
  }
}
```

## uip is connectors import

Package the local connector into a zip and create or update it on the tenant by key — created the first time, updated on every run after that.

:::note
Use this to publish local connector changes to a tenant, or to create a tenant connector from a local directory for the first time. To download or search tenant connectors instead, use `connectors download` / `connectors list`.
:::

### Arguments

None.

### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Connector directory, or any parent of `app/element/element.json`. Defaults to the current directory. |
| `--tenant <name>` | name | Override the tenant for the API calls. |

### Example

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

### Data shape (--output json)

```json
{
  "Code": "ConnectorImported",
  "Data": {
    "Id": 123,
    "Key": "design-myorg-acmewidgets",
    "Name": "Acme Widgets",
    "Operation": "Created"
  }
}
```

`Operation` is `"Created"` the first time a given connector key is imported, `"Updated"` on every subsequent import.

## uip is connectors publish

Promote a design connector to a tenant-wide CUSTOM connector. Fire-and-forget by default — returns a `PublishId` to poll with `publish-status`; pass `--wait` to poll internally instead.

:::note
Use this after `connectors import` succeeds, to make the connector visible to every user in the tenant — or to re-publish a new version of an already-published connector (bump `element-metadata.json:latestVersion` first). This does **not** push local file changes to a tenant — that's `connectors import`. `publish` only operates on what's already been imported.
:::

### Arguments

None.

### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Path to the connector directory. Same resolution order as [Concepts](#concepts) above. |
| `--version <semver>` | semver | Override the version from `element-metadata.json:latestVersion`. Rarely needed. |
| `--connector-id <id>` | integer | Bypass the get-by-key lookup with an explicit numeric ID. Rarely needed. |
| `--wait` | flag | Poll status until `SUCCESS`/`FAILURE`/timeout instead of returning immediately. |
| `--timeout-seconds <seconds>` | integer | Polling timeout when `--wait` is set. Default `600` (10 minutes). |
| `--tenant <name>` | name | Use this tenant's auth instead of the logged-in default. |

Both `--connector-id` and `--timeout-seconds` are validated client-side as positive integers before any network call.

### Examples

```bash
# Fire-and-forget — returns a PublishId to poll separately (~5-10 min until Studio Web shows it)
uip is connectors publish
```

```bash
# Block until publish completes (or the 10-minute default timeout)
uip is connectors publish --wait
```

### Data shape (--output json)

```json
{
  "Code": "ConnectorPublishStarted",
  "Data": {
    "ConnectorKey": "design-acmecorp-stripe",
    "ConnectorId": 42,
    "Version": "1.0.0",
    "PublishId": 99,
    "Status": "IN_PROGRESS",
    "Completed": false
  }
}
```

With `--wait`, the same `Code: "ConnectorPublishStarted"` is used, but `Data` reflects the final polled state (`Status: "SUCCESS"` or `"FAILURE"`, `Completed: true`) instead of the initial `IN_PROGRESS` snapshot.

## uip is connectors publish-status

Poll a publish job's status by `publish-id`. Returns the server's status verbatim.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<publish-id>` | yes | Publish job ID returned by `connectors publish`. |

### Options

| Long | Value | Description |
|---|---|---|
| `--tenant <name>` | name | Use this tenant's auth instead of the logged-in default. |

### Example

```bash
uip is connectors publish-status 99
```

### Data shape (--output json)

```json
{
  "Code": "ConnectorPublishStatus",
  "Data": { "PublishId": "99", "Status": "SUCCESS" }
}
```

`Status` is one of `IN_PROGRESS`, `SUCCESS`, or `FAILURE`, passed through verbatim from the server. A failed publish adds a `Message` field with the failure detail.

## Related

- [Init & connector](./uip-is-connectors-builder-init.md) — scaffold the local connector `download`/`import`/`publish` operate on.
- [Auth](./uip-is-connectors-builder-auth.md) — configure the connector's authentication scheme.
- [Activity](./uip-is-connectors-builder-activity.md) — define what the connector's activities do.
- [Activity hooks](./uip-is-connectors-builder-activity-hooks.md) — JavaScript pre/post-request transforms.
- [Trigger & state](./uip-is-connectors-builder-trigger.md) — event triggers and low-level file edits.
- [`uip is connectors`](./uip-is-connectors.md) — the read-only catalog these commands feed into once published.

## See also

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