# uip agent deploy

> `uip agent deploy` installs and activates a previously published agent package version into an Orchestrator folder. It drives the full Solutions deployment pipeline — configure → deploy → install → provision → activate — and polls until each phase reaches a terminal state.

`uip agent deploy` installs and activates a previously published agent package version into an Orchestrator folder. It drives the full Solutions deployment pipeline — configure → deploy → install → provision → activate — and polls until each phase reaches a terminal state.

By default the command also **provisions** the target folder for immediate execution: it assigns a tenant-level serverless machine template and binds a robot user with the `Automation User` role to the folder. Provisioning failures are surfaced as warnings rather than errors (you can assign the machine and user manually after the fact).

Requires an active CLI session (`uip login`).

## Synopsis

```
uip agent deploy <packageVersionKey>
                 [-n <name>]
                 [--folder-key <guid>]
                 [--force-activate] [--skip-activate]
                 [-t <tenant>]
                 [--timeout <seconds>]
                 [--login-validity <minutes>]
```

All `uip agent deploy` invocations honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md), with the deployment-specific overrides noted below.

## Arguments

- `<packageVersionKey>` *(required)* — Package version key returned by [`uip agent publish`](./uip-agent-publish.md) (default upload path). GUID.

## Options

| Flag | Default | Purpose |
|---|---|---|
| `-n, --name <name>` | `agent-<timestamp>` | Deployment name. Becomes the display name in Orchestrator and — for auto-created folders — the folder name. |
| `--folder-key <guid>` | — *(auto-create)* | Installation folder key (GUID). If omitted, a new folder is created automatically during install. |
| `--force-activate` | off | Force activation even if a previous deployment exists at this configuration key. |
| `--skip-activate` | off | Stop after the install phase; do not activate. Useful when you want to review the install before releasing the agent. |
| `-t, --tenant <tenant>` | *login tenant* | Target tenant. Required if the login session has no default tenant. |
| `--timeout <seconds>` | `120` | Maximum seconds to wait for each poll phase (install, activate) to reach a terminal state. On timeout, the command exits with code `2`. |
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

## Examples

```bash
# Deploy to an auto-created folder named "invoice-agent"
uip agent deploy a1b2c3d4-0000-0000-0000-000000000050 --name invoice-agent

# Deploy into an existing folder
uip agent deploy <PackageVersionKey> --folder-key <FolderGuid>

# Install only; do not activate (review in Orchestrator first)
uip agent deploy <PackageVersionKey> --skip-activate

# Force re-activation of a replacement deployment
uip agent deploy <PackageVersionKey> --force-activate

# Longer timeout for slow environments
uip agent deploy <PackageVersionKey> --timeout 600
```

## Data shape (--output json)

**Install + activate completed** (`Code: "AgentDeploy"`):

```json
{
  "Code": "AgentDeploy",
  "Data": {
    "DeploymentKey": "a1b2c3d4-0000-0000-0000-000000000060",
    "DeploymentName": "invoice-agent",
    "Status": "SuccessfulActivate",
    "FolderKey": "a1b2c3d4-0000-0000-0000-000000000070",
    "FolderId": 42,
    "FolderName": "invoice-agent",
    "ConfigurationKey": "a1b2c3d4-0000-0000-0000-000000000080",
    "PackageVersionKey": "a1b2c3d4-0000-0000-0000-000000000050"
  }
}
```

**Install only** (`--skip-activate` or not ready to activate): same shape, with `Status` reflecting the install phase (`SuccessfulInstall`, `FailedInstall`) and `FolderName` omitted when the folder could not be resolved.

- `FolderId` — numeric Org Unit ID of the folder, populated only when auto-provisioning succeeded. Pass it directly to `uip agent run list --folder-id`.
- `FolderKey` — GUID of the installation folder.
- `ConfigurationKey` — key of the Solutions `Configuration` created by this deploy.
- `PackageVersionKey` — echoed back from input for convenience.

## Exit codes

In addition to the standard CLI codes:

- `0` — install (and optionally activate) completed successfully.
- `1` — deployment failed (`FailedInstall`, `FailedActivate`), polling errored, or any other failure.
- `2` — a poll phase timed out (see `--timeout`). Deployment may still complete in Orchestrator; re-run with a longer timeout, or inspect status in the Orchestrator UI.

See [Exit codes](./exit-codes.md) for the shared contract.

## Provisioning detail

When a folder is auto-created (no `--folder-key`), deploy tries to:

1. Assign a tenant-level serverless machine template to the folder. If no serverless template exists in the tenant, provisioning fails and the deploy surfaces a warning — you must assign one manually.
2. Pick an assignable user and grant it the `Automation User` role in the folder. If no such role exists in the tenant, provisioning fails with a warning.

Conflicts (HTTP 409) during machine or user assignment are treated as idempotent successes.

## Related

- [`uip agent publish`](./uip-agent-publish.md) — produces the `PackageVersionKey` this command consumes.
- [`uip agent run start`](./uip-agent-run.md) — start a job against a release in the deployed folder.
- [`uip agent run list`](./uip-agent-run.md) — list the releases the deployment created.

## See also

- [Orchestrator: jobs](./uip-orchestrator-jobs.md) — the underlying job model.
- [Authentication](./authentication.md) — sessions, tenants, and `--login-validity`.
- [Global options](./global-options.md), [Exit codes](./exit-codes.md).