UiPath Documentation
uipath-cli
latest
false

UiPath CLI user guide

Last updated May 7, 2026

uip agent run

uip agent run starts and monitors agent jobs on Orchestrator. Internally, each subcommand calls the standard Orchestrator Jobs / Releases OData endpoints — the same endpoints that uip or jobs exposes — scoped to the releases produced by uip agent deploy.

Every subcommand requires an active CLI session (uip login). If no --folder-id is passed, the command uses the folder bound to the current session.

Synopsis​

uip agent run start <releaseKeyOrName> [-i <json>] [--folder-id <id>] [-t <tenant>] [--login-validity <minutes>]
uip agent run status <jobId>                         [--folder-id <id>] [-t <tenant>] [--login-validity <minutes>]
uip agent run list                                   [--folder-id <id>] [--filter <odata>] [-t <tenant>] [--login-validity <minutes>]
uip agent run start <releaseKeyOrName> [-i <json>] [--folder-id <id>] [-t <tenant>] [--login-validity <minutes>]
uip agent run status <jobId>                         [--folder-id <id>] [-t <tenant>] [--login-validity <minutes>]
uip agent run list                                   [--folder-id <id>] [--filter <odata>] [-t <tenant>] [--login-validity <minutes>]

All uip agent run subcommands honor the global options (--output, --output-filter, --log-level, --log-file). Exit codes follow the standard contract.

uip agent run start​

Start a job for a deployed agent release.

Arguments​

  • <releaseKeyOrName> (required) — Either a release key (GUID) or a release name. If the value is not a GUID, the command performs a name lookup against the Releases OData endpoint ($filter=Name eq '<name>').

Options​

FlagDefaultPurpose
-i, --inputs <json>{}Input arguments as a JSON string. Must be valid JSON.
--folder-id <id>login folderOrchestrator folder Org Unit ID. Sent as X-UIPATH-OrganizationUnitId.
-t, --tenant <tenant>login tenantTarget tenant.
--login-validity <minutes>10Minimum minutes of token validity required.

Examples​

# Start by release key (the exact key from 'agent run list')
uip agent run start a1b2c3d4-0000-0000-0000-000000000401 -i '{"input":"hello"}'

# Start by release name (resolved via OData lookup)
uip agent run start InvoiceAgent -i '{"invoiceUrl":"…"}' --folder-id 42

# Start with no inputs
uip agent run start InvoiceAgent
# Start by release key (the exact key from 'agent run list')
uip agent run start a1b2c3d4-0000-0000-0000-000000000401 -i '{"input":"hello"}'

# Start by release name (resolved via OData lookup)
uip agent run start InvoiceAgent -i '{"invoiceUrl":"…"}' --folder-id 42

# Start with no inputs
uip agent run start InvoiceAgent

Data shape (--output json)​

{
  "Code": "AgentJobStarted",
  "Data": {
    "JobId": 12345,
    "JobKey": "a1b2c3d4-0000-0000-0000-000000000410",
    "State": "Pending"
  }
}
{
  "Code": "AgentJobStarted",
  "Data": {
    "JobId": 12345,
    "JobKey": "a1b2c3d4-0000-0000-0000-000000000410",
    "State": "Pending"
  }
}

JobId is the numeric ID you pass to uip agent run status. JobKey is the GUID equivalent, useful for cross-references against the Orchestrator UI or uip or jobs commands. Jobs are started with Strategy: ModernJobsCount and JobsCount: 1.

uip agent run status​

Fetch the current state of a single job.

Arguments​

  • <jobId> (required) — Numeric Orchestrator job ID (from run start or uip or jobs list).

Options​

Same as run start (--folder-id, -t/--tenant, --login-validity).

Examples​

# Quick status check
uip agent run status 12345

# Explicit folder
uip agent run status 12345 --folder-id 42
# Quick status check
uip agent run status 12345

# Explicit folder
uip agent run status 12345 --folder-id 42

Data shape (--output json)​

{
  "Code": "AgentJobStatus",
  "Data": {
    "JobId": 12345,
    "State": "Successful",
    "ReleaseName": "InvoiceAgent",
    "StartTime": "2025-04-15T10:30:00Z",
    "EndTime": "2025-04-15T10:31:12Z",
    "Info": "…",
    "Output": { "...": "..." }
  }
}
{
  "Code": "AgentJobStatus",
  "Data": {
    "JobId": 12345,
    "State": "Successful",
    "ReleaseName": "InvoiceAgent",
    "StartTime": "2025-04-15T10:30:00Z",
    "EndTime": "2025-04-15T10:31:12Z",
    "Info": "…",
    "Output": { "...": "..." }
  }
}
  • State values mirror Orchestrator's job states (Pending, Running, Successful, Faulted, Stopped, Suspended, …).
  • Info is only present when the job carries a status message (typically on failure).
  • Output is OutputArguments parsed as JSON. If parsing fails, the raw string is returned instead.

uip agent run list​

List the agent releases available in a folder.

Arguments​

None.

Options​

FlagDefaultPurpose
--folder-id <id>login folderOrchestrator folder Org Unit ID.
--filter <odata>—Additional OData $filter expression appended to the default query (which already sorts by Name).
-t, --tenant <tenant>login tenantTarget tenant.
--login-validity <minutes>10Minimum minutes of token validity required.

Examples​

# List all releases in the login folder
uip agent run list

# List in a specific folder
uip agent run list --folder-id 42

# Filter by name prefix
uip agent run list --filter "startswith(Name,'Invoice')"
# List all releases in the login folder
uip agent run list

# List in a specific folder
uip agent run list --folder-id 42

# Filter by name prefix
uip agent run list --filter "startswith(Name,'Invoice')"

Data shape (--output json)​

{
  "Code": "AgentReleaseList",
  "Data": [
    {
      "Name": "InvoiceAgent",
      "ReleaseKey": "a1b2c3d4-0000-0000-0000-000000000401",
      "ProcessKey": "InvoiceAgent",
      "Version": "1.0.0",
      "FolderId": 42
    }
  ]
}
{
  "Code": "AgentReleaseList",
  "Data": [
    {
      "Name": "InvoiceAgent",
      "ReleaseKey": "a1b2c3d4-0000-0000-0000-000000000401",
      "ProcessKey": "InvoiceAgent",
      "Version": "1.0.0",
      "FolderId": 42
    }
  ]
}

An empty folder returns a Message log entry (No releases found in this folder. Publish an agent first.) and no success payload.

See also​

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated