- Overview
- Get started
- Concepts
- Using UiPath CLI
- How-to guides
- CI/CD recipes
- Command reference
- Overview
- Exit codes
- Global options
- uip codedagent
- uip coder
- uip context-grounding
- uip docsai
- uip function
- uip guardrails
- uip llm-configuration
- uip llm-gateway
- uip model-hub
- add-test-data-entity
- add-test-data-queue
- add-test-data-variation
- analyze
- build
- create-project
- diff
- find-activities
- get-analyzer-rules
- get-default-activity-xaml
- get-errors
- get-manual-test-cases
- get-manual-test-steps
- get-library-object-repository
- get-object-repository
- get-versions
- get-workflow-example
- indicate-application
- indicate-element
- inspect-package
- install-data-fabric-entities
- install-or-update-packages
- list-data-fabric-entities
- list-instances
- list-workflow-examples
- pack
- publish
- remote
- restore
- run, debug & execution
- run-file
- search-templates
- start-studio
- stop-execution
- tm
- uia
- uip tasks
- uip traces
- uip traces feedback
- Migration
- Reference & support
uip rpa remote
Syntax and options for `uip rpa remote`, which configures and drives a remote Orchestrator unattended robot — target configuration, remote sessions, process execution, and file transfer.
uip rpa remote operates on a remote Orchestrator unattended robot: configure which machine, robot, and runtime to target, start or stop the remote session on it, run shell commands on it, and transfer files to and from it. Once configured, uip rpa run --remote and debug start --remote route execution to that machine.
Every verb requires Orchestrator sign-in (uip login).
Synopsis
uip rpa remote configure --machine <name> [--folder-path <path>] [--robot <name>] [--runtime <name>] [--live-authoring | --remote-run-only]
uip rpa remote configure --folder-path <path> [--live-authoring | --remote-run-only]
uip rpa remote status
uip rpa remote start
uip rpa remote stop
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 --machine <name> [--folder-path <path>] [--robot <name>] [--runtime <name>] [--live-authoring | --remote-run-only]
uip rpa remote configure --folder-path <path> [--live-authoring | --remote-run-only]
uip rpa remote status
uip rpa remote start
uip rpa remote stop
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>
Connection modes
A remote target runs in one of two modes. remote configure sets the mode.
| Mode | Flag | Behavior |
|---|---|---|
| Remote Run Only | --remote-run-only | Each run, debug session, or remote command is an Orchestrator job of its own. No remote UI Automation session is available. This is the default for a target that has no stored mode. |
| Live Authoring | --live-authoring | One long-lived remote session job serves every remote command, run, and debug session. The remote UI Automation design session is available, and the remote screen is streamed. |
uip rpa remote configure
Resolve and store the remote target: the folder, plus the robot, machine, and runtime resolved within it, and the connection mode. The connection is stored per project, in the project's .local/RemoteConnection.json file. Run from the Studio integrated terminal, the command configures both the headless backend and Studio.
Options
| Long | Value | Required | Description |
|---|---|---|---|
--machine <name> | string | conditionally | Orchestrator machine name to run the unattended robot on. Required unless --folder-path is passed alone to reuse a stored connection. |
--folder-path <path> | string | conditionally | Fully-qualified Orchestrator folder the robot and machine belong to (for example, Shared/Finance). The robot, machine, and runtime are resolved within it. With --machine, it defaults to the backend's current folder. Passed alone, it selects the connection stored for that folder, and fails when none is stored. |
--robot <name> | string | no | Robot or user account to run as. Defaults to the machine's default identity. Requires --machine. |
--runtime <name> | string | no | Connected runtime (host or session) name. Ignored for serverless machines; set it to target a specific connected session on a classic machine. Requires --machine. |
--live-authoring | flag | no | Use the target in Live Authoring mode. Mutually exclusive with --remote-run-only. |
--remote-run-only | flag | no | Use the target in Remote Run Only mode. Mutually exclusive with --live-authoring. |
Passing both --live-authoring and --remote-run-only fails. Passing neither keeps the current mode:
- With
--machine, the host's current mode applies, or the folder's stored mode when the host has no connection yet. - With
--folder-pathalone, the mode stored for that folder applies. - From the Studio integrated terminal, the headless backend takes the mode that Studio keeps.
Examples
# Configure a target for remote runs
uip rpa remote configure --machine BotMachine --folder-path "Shared/Finance"
# Configure a target for live authoring
uip rpa remote configure --machine BotMachine --folder-path "Shared/Finance" --live-authoring
# Reuse the connection stored for a folder
uip rpa remote configure --folder-path "Shared/Finance"
# Configure a target for remote runs
uip rpa remote configure --machine BotMachine --folder-path "Shared/Finance"
# Configure a target for live authoring
uip rpa remote configure --machine BotMachine --folder-path "Shared/Finance" --live-authoring
# Reuse the connection stored for a folder
uip rpa remote configure --folder-path "Shared/Finance"
Data shape (--output json)
Raw pass-through of the backend's { success, ...resolved-config } payload, including the resolved folder, robot, machine, and runtime once matched.
uip rpa remote status
Show the remote connection currently configured, as resolved against the connected Orchestrator. Read-only: it does not change the target or start anything. From the Studio integrated terminal, it shows Studio Desktop's connection beside the headless backend's. No options.
The output includes remoteSessionEnabled, the configured folder, and remoteMachine (host:port, or null for an unattended robot connection).
Example
uip rpa remote status
uip rpa remote status
uip rpa remote start
Start the remote session: bring up the app on the configured remote agent that remote runs, debugging, and remote commands travel over. Fails when no target is configured, so run remote configure first. Starting a session that is already running does nothing; reconfiguring the target restarts it. No options.
The UI Automation design host does not start here. The first uip rpa uia command that uses --remote starts it. Run from the Studio integrated terminal, remote start starts the session for both the headless backend and Studio.
Example
uip rpa remote start
uip rpa remote start
uip rpa remote stop
Stop the remote session: tear down the connection to the remote agent and release it, including the UI Automation design host when one was started. Succeeds when no session is running or no target is configured. A later remote start, or a uia command with --remote, brings a session up again. Run from the Studio integrated terminal, it stops the session for both the headless backend and Studio. No options.
Example
uip rpa remote stop
uip rpa remote stop
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: the command always runs on the remote machine. In Live Authoring mode it runs on the shared remote session; in Remote Run Only mode it runs as an Orchestrator job of its own.
Options
| Long | Value | Required | Description |
|---|---|---|---|
--command <cmd> | string | yes | Shell command line to run remotely (for example, dir or ls -la). When a package is restored, it 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. |
--package-version <v> | string | conditionally | Version of --package-id to restore. Required when --package-id is set; passing one without the other fails. |
--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
uip rpa remote exec --command "dir" --timeout 30
uip rpa remote exec --command "dir" --timeout 30
uip rpa remote upload-file
Upload a local file to the configured remote agent. The file travels through a temporary Orchestrator storage bucket that is deleted afterwards. In Live Authoring mode the transfer runs on the shared remote session; in Remote Run Only mode it runs as an Orchestrator job of its own.
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
uip rpa remote upload-file --local-path ./data.csv --remote-path "C:\Bots\data.csv"
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. The file travels through a temporary Orchestrator storage bucket that is deleted afterwards. In Live Authoring mode the transfer runs on the shared remote session; in Remote Run Only mode it runs as an Orchestrator job of its own.
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
uip rpa remote download-file --remote-path "C:\Bots\output.log" --local-path ./output.log
uip rpa remote download-file --remote-path "C:\Bots\output.log" --local-path ./output.log
Related
uip rpa run/debug— the--remoteflag this group's target configures.uip rpa uia— driven remotely once a remote session is running.
See also
- Synopsis
- Connection modes
- uip rpa remote configure
- Options
- Examples
- Data shape (--output json)
- uip rpa remote status
- Example
- uip rpa remote start
- Example
- uip rpa remote stop
- Example
- uip rpa remote exec
- Options
- Example
- uip rpa remote upload-file
- Options
- Example
- uip rpa remote download-file
- Options
- Example
- Related
- See also