# uip rpa remote

> Syntax and options for `uip rpa remote`, which configures and drives a remote Orchestrator unattended robot — target configuration, UI Automation sessions, process execution, and file transfer.

`uip rpa remote` operates on a remote Orchestrator unattended robot: configure which machine/robot/runtime to target, start or stop a remote UI Automation design session on it, run shell commands on it, and transfer files to/from it. Once configured, [`uip rpa run --remote`](./uip-rpa-run-debug.md#uip-rpa-run) and [`debug start --remote`](./uip-rpa-run-debug.md#uip-rpa-debug-start) route execution to that machine instead of running locally.

Requires Orchestrator sign-in (`uip login`) for every verb.

## Synopsis

```text
uip rpa remote configure --machine <name> [--folder-path <path>] [--robot <name>] [--runtime <name>] [--live-authoring | --remote-run-only]
uip rpa remote status
uip rpa remote start
uip rpa remote stop
uip rpa remote echo --message <text>
uip rpa remote exec --command <cmd> [--package-id <id> --package-version <v>] [--working-directory <dir>] [--timeout <seconds>]
uip rpa remote upload-file --local-path <path> --remote-path <path>
uip rpa remote download-file --remote-path <path> --local-path <path>
```

## uip rpa remote configure

Resolve and store the remote debugging target (folder → robot → machine → runtime), and start the remote UI Automation design session on it. `remote stop` turns the session off.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--machine <name>` | string | **yes** | Orchestrator machine name to run the unattended robot on. |
| `--folder-path <path>` | string | no | Fully-qualified Orchestrator folder the robot/machine belong to (e.g. `Shared/Finance`) — the robot, machine, and runtime are resolved within it. Defaults to the backend's current folder. |
| `--robot <name>` | string | no | Robot/user account to run as. Defaults to the machine's default identity. |
| `--runtime <name>` | string | no | Connected runtime (host/session) name. Ignored for serverless machines; set it to target a specific connected session on a classic machine. |
| `--live-authoring` | flag | no | Use the target for live authoring: one long-lived remote session job serves every remote command, run and debug session; the remote UI Automation design session becomes available and the remote screen is streamed. Mutually exclusive with `--remote-run-only`. Required before `remote echo` will work. |
| `--remote-run-only` | flag | no | Use the target for remote runs only: a run or debug session is its own Orchestrator job, with no remote UI Automation session. This is the default for a target that has never had a mode stored. Mutually exclusive with `--live-authoring`. |

Passing both `--live-authoring` and `--remote-run-only` fails client-side — they are the two modes of one connection; pass at most one. Passing neither leaves the stored mode unchanged.

### Example

```bash
uip rpa remote configure --machine BotMachine --folder-path "Shared/Finance"
```

### Data shape (--output json)

Raw pass-through of the backend's `{ success, ...resolved-config }` payload — includes the resolved folder/robot/machine/runtime once matched.

## uip rpa remote status

Show the remote connection currently configured for the signed-in tenant, as resolved against Orchestrator. Read-only — does not change or start anything. No options.

### Example

```bash
uip rpa remote status
```

## uip rpa remote start

Start remote UI Automation: set up a UIA design-experience session on the configured remote agent, so [`uip rpa uia`](./uip-rpa-uia.md) commands with `--remote` drive that machine. Fails if no target is configured (`remote configure` first). Starting an already-running session is a no-op; reconfiguring to a different target restarts it. No options.

### Example

```bash
uip rpa remote start
```

## uip rpa remote stop

Tear down the current remote UIA session and release the agent. Idempotent — succeeds even when no session is running or the target is no longer configured. A later `uia --remote` call starts a new session automatically. No options.

### Example

```bash
uip rpa remote stop
```

## uip rpa remote echo

Round-trip a message off the RemoteSessionAgent running on the configured remote agent and print the reply — a connectivity check. **Live Authoring only** (`remote configure --live-authoring`); Remote Run Only has no agent to answer. Starts the agent on first use; every echo travels on its own private channel, so concurrent callers only ever see their own reply.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--message <text>` | string | **yes** | Text the RemoteSessionAgent echoes back — useful for telling concurrent callers' replies apart. |

### Example

```bash
uip rpa remote echo --message "ping"
```

## uip rpa remote exec

Execute a shell command on the configured remote agent (`cmd.exe /c` on Windows, `/bin/sh -c` otherwise), streaming output back live. There is no local mode — this always runs on the remote machine.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--command <cmd>` | string | **yes** | Shell command line to run remotely (e.g. `dir`, `ls -la`). When a package is restored (see below), can be a path relative to the package folder. |
| `--package-id <id>` | string | conditionally | NuGet package to restore on the remote machine before running the command. Requires `--package-version` together. |
| `--package-version <v>` | string | conditionally | Version of `--package-id` to restore. Required when `--package-id` is set — passing one without the other fails client-side. |
| `--working-directory <dir>` | string | no | Working directory for the command. Defaults to the restored package folder when a package is restored, otherwise the remote machine's current directory. |
| `--timeout <seconds>` | number | no | Kill the command after this many seconds. Omit for no timeout. |

### Example

```bash
uip rpa remote exec --command "dir" --timeout 30
```

## uip rpa remote upload-file

Upload a local file to the configured remote agent, transferred through a temporary Orchestrator storage bucket (created and deleted automatically).

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--local-path <path>` | string | **yes** | Path to the local file to upload. |
| `--remote-path <path>` | string | **yes** | Destination path on the remote machine. Parent directories are created. |

### Example

```bash
uip rpa remote upload-file --local-path ./data.csv --remote-path "C:\Bots\data.csv"
```

## uip rpa remote download-file

Download a file from the configured remote agent to a local path, transferred through a temporary Orchestrator storage bucket.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--remote-path <path>` | string | **yes** | Path of the file on the remote machine to download. |
| `--local-path <path>` | string | **yes** | Destination path locally. Parent directories are created. |

### Example

```bash
uip rpa remote download-file --remote-path "C:\Bots\output.log" --local-path ./output.log
```

## Related

- [`uip rpa run`/`debug`](./uip-rpa-run-debug.md) — the `--remote` flag this group's target configures.
- [`uip rpa uia`](./uip-rpa-uia.md) — driven remotely once `remote start` is active.

## See also

- [RPA tool overview](./uip-rpa.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)