@uipath/skills 1.195.0

package/skills/uipath-platform/references/orchestrator/manage-sessions.md

@@ -0,0 +1,217 @@
+# Manage Sessions
+
+Monitor robot sessions, check runtime availability, toggle debug mode, and manage maintenance windows.
+
+> For full option details on any command, use `--help` (e.g., `uip or sessions attended list --help`)
+
+## When to Use
+
+- Checking robot availability before starting jobs
+- Debugging connectivity issues with connected robots
+- Enabling debug mode for Studio remote debugging
+- Planning and executing maintenance windows
+- Cleaning up disconnected or stale sessions
+
+## Prerequisites
+
+- Authenticated (`uip login`)
+- Environment set up with folders and machines (see [setup-environment.md](setup-environment.md))
+
+---
+
+## Step 1: Check Folder Runtimes
+
+Before starting jobs, verify that the target folder has available runtime slots:
+
+```bash
+uip or folders runtimes <folder-key> --output json
+```
+
+This shows runtime capacity per type: total slots, connected machines, and available (idle) slots. If available slots are zero, jobs will queue in Pending state until a slot frees up.
+
+## Step 2: List Attended Sessions
+
+View attended robot sessions (human-interactive robots via UiPath Assistant):
+
+```bash
+uip or sessions attended list --output json
+
+# Filter by folder
+uip or sessions attended list --folder-path "Finance" --output json
+
+# Filter by state
+uip or sessions attended list --state Available --output json
+```
+
+Session states: `Available`, `Busy`, `Disconnected`, `Unknown`.
+
+## Step 3: List Unattended Sessions
+
+View unattended robot sessions (autonomous execution robots):
+
+```bash
+uip or sessions unattended list --output json
+
+# Filter by folder and runtime type
+uip or sessions unattended list \
+  --folder-path "Production" \
+  --runtime-type Unattended \
+  --output json
+```
+
+## Step 4: List Machine Sessions
+
+View all sessions on a specific machine:
+
+```bash
+uip or sessions machines list <machine-key> --output json
+
+# Scoped to a folder
+uip or sessions machines list <machine-key> \
+  --folder-path "Production" --output json
+```
+
+## Step 5: List Active Usernames
+
+See which users currently have active sessions:
+
+```bash
+uip or sessions list-usernames --output json
+```
+
+## Step 6: List User Executors
+
+See which execution slots are allocated to users:
+
+```bash
+uip or sessions list-user-executors --output json
+```
+
+## Step 7: Toggle Debug Mode
+
+Enable debug mode on a session to allow Studio to connect remotely for live debugging:
+
+```bash
+# Enable debug mode for 30 minutes
+uip or sessions toggle-debug-mode <session-id> \
+  --enabled true --minutes 30 --output json
+
+# Disable debug mode
+uip or sessions toggle-debug-mode <session-id> \
+  --enabled false --output json
+```
+
+Debug mode auto-expires after the specified `--minutes` duration. While active, Studio can attach to the robot session for step-through debugging.
+
+## Step 8: Set Maintenance Mode
+
+Put a session into maintenance mode to prevent new jobs from being assigned:
+
+```bash
+# Enable maintenance mode
+uip or sessions set-maintenance-mode <session-id> \
+  --maintenance-mode Enabled --output json
+
+# Enable and stop current jobs
+uip or sessions set-maintenance-mode <session-id> \
+  --maintenance-mode Enabled \
+  --stop-jobs-strategy SoftStop --output json
+
+# Force-stop current jobs during maintenance
+uip or sessions set-maintenance-mode <session-id> \
+  --maintenance-mode Enabled \
+  --stop-jobs-strategy Kill --output json
+
+# Disable maintenance mode
+uip or sessions set-maintenance-mode <session-id> \
+  --maintenance-mode Disabled --output json
+```
+
+While maintenance mode is enabled, the Orchestrator will not assign new jobs to the session. Existing running jobs continue unless a `--stop-jobs-strategy` is specified.
+
+## Step 9: Clean Up Inactive Sessions
+
+Remove disconnected or stale sessions:
+
+```bash
+# Delete specific inactive sessions
+uip or sessions delete-inactive <session-id-1> <session-id-2> --output json
+
+# Delete ALL inactive sessions (no IDs = clean all)
+uip or sessions delete-inactive --output json
+```
+
+**Warning:** Running `delete-inactive` without session IDs removes ALL inactive sessions in the tenant. Use with caution.
+
+---
+
+## Complete Example
+
+Check runtime availability, inspect sessions, enable debug mode for troubleshooting, then clean up.
+
+```bash
+# 1. Check if the folder has available runtimes
+uip or folders runtimes <folder-key> --output json
+
+# 2. List unattended sessions to find the target robot
+uip or sessions unattended list \
+  --folder-path "Production" --output json
+# -> Note the session Id for the robot you need to debug
+
+# 3. Enable debug mode for 30 minutes
+uip or sessions toggle-debug-mode <session-id> \
+  --enabled true --minutes 30 --output json
+
+# 4. (Attach Studio, debug the issue...)
+
+# 5. Disable debug mode when done
+uip or sessions toggle-debug-mode <session-id> \
+  --enabled false --output json
+
+# 6. Clean up any stale disconnected sessions
+uip or sessions delete-inactive --output json
+```
+
+---
+
+## Variations and Gotchas
+
+### Folder Scope
+
+Sessions are tenant-wide by default. Add `--folder-path` to scope results to a specific folder. This applies to:
+
+- `sessions attended list`
+- `sessions unattended list`
+- `sessions machines list`
+
+Without `--folder-path`, you see all sessions across the tenant (requires appropriate permissions).
+
+### Debug Mode Auto-Expiry
+
+Debug mode automatically disables after the `--minutes` duration elapses. There is no persistent debug mode -- you must specify a duration. If you need more time, re-enable it before it expires.
+
+### Maintenance Mode and Job Assignment
+
+Maintenance mode prevents **new** job assignment only. It does not pause or stop jobs that are already running unless you explicitly set `--stop-jobs-strategy`:
+
+| Strategy | Behavior |
+|----------|----------|
+| (none) | Running jobs continue, no new jobs assigned |
+| `SoftStop` | Running jobs receive a graceful stop signal |
+| `Kill` | Running jobs are forcefully terminated |
+
+### Cleaning Inactive Sessions
+
+`delete-inactive` targets sessions in a `Disconnected` state. It will not affect `Available` or `Busy` sessions. Omitting session IDs cleans **all** inactive sessions -- useful for periodic maintenance but should be confirmed before running in production.
+
+### Session vs Machine
+
+A **machine** is the registered host (physical or virtual). A **session** is a runtime connection from a robot on that machine to Orchestrator. One machine can host multiple sessions (e.g., multiple user sessions on a terminal server).
+
+---
+
+## Related
+
+- [setup-environment.md](setup-environment.md) -- Folder creation, machine assignment, runtime configuration
+- [run-jobs.md](run-jobs.md) -- Start and monitor jobs (check runtimes before starting)
+- [orchestrator.md](orchestrator.md) -- Orchestrator concepts and common flags

package/skills/uipath-platform/references/orchestrator/orchestrator.md

@@ -0,0 +1,130 @@
+# Orchestrator (`uip or`)
+
+Manage Orchestrator infrastructure -- folders, users, machines, jobs, processes, and more.
+
+> For full option details on any command, use `--help` (e.g., `uip or folders list --help`).
+
+---
+
+## Common Flags
+
+All `uip or` commands share a set of cross-cutting options:
+
+| Flag | Scope | Purpose |
+|------|-------|---------|
+| `--tenant <name>` | All commands | Override the default tenant (set during `uip login tenant set`). |
+| `--output json` | All commands | Emit structured JSON instead of table output. Always use this when parsing output programmatically. |
+| `--limit <n>` | List commands | Number of items to return (default 50). |
+| `--offset <n>` | List commands | Number of items to skip for pagination. |
+| `--sort-by <field>` | List commands | OData-style sort (e.g., `'Name asc'`, `'Id desc'`). |
+| `--all-fields` | Most get/list commands | Return the full API DTO instead of the curated summary. Use when you need a field the curated view drops. Note: curated keys are PascalCase, raw DTO keys are camelCase — the shapes do not share casing. |
+| `--output-filter <expr>` | All commands | JMESPath expression to filter/reshape JSON output (e.g., `--output-filter "Data[].Key"`). |
+
+**Pagination pattern.** List responses include a `Pagination` block with `Returned`, `Limit`, `Offset`, and `HasMore`. When `HasMore` is `true`, increment `--offset` by `--limit` and fetch again. Continue until `HasMore` is `false` or `Returned < Limit`.
+
+---
+
+## Workflow References
+
+Each workflow doc covers a multi-command choreography for a specific goal. Load the one that matches your task.
+
+| Workflow | File | Covers |
+|----------|------|--------|
+| Setup Environment | [setup-environment.md](setup-environment.md) | Folders, users, roles, machines, licenses |
+| Run Jobs | [run-jobs.md](run-jobs.md) | Packages, processes, jobs, logs, traces |
+| Manage Sessions | [manage-sessions.md](manage-sessions.md) | Sessions, runtimes, maintenance mode |
+| Tenant Admin | [tenant-admin.md](tenant-admin.md) | Settings, calendars, audit logs, credential stores, feeds, attachments |
+
+---
+
+## Key Concepts
+
+### Platform Hierarchy
+
+```
+Organization (cloud.uipath.com)
+  +-- Tenant              Isolated environment (dev, staging, prod)
+        +-- Folder         Logical container for resources
+              +-- Processes, Jobs, Assets, Queues, Machines, etc.
+```
+
+All CLI operations happen within a **tenant** context (set via `uip login tenant set` or `--tenant`). Most resource operations also require a **folder** context (`--folder-path` or `--folder-key`).
+
+Tenants provide complete isolation of all Orchestrator entities. Each tenant has its own folders, users, machines, packages, and configuration. A typical setup uses separate tenants for Development, Staging/UAT, and Production.
+
+### Folder Types
+
+| Type | Description |
+|------|-------------|
+| **Standard** | Regular folder for organizing resources. Supports nesting. |
+| **Personal** | Per-user workspace. Flat (no hierarchy). |
+| **Solution** | Created by solution deployments. Managed by the solution framework. |
+| **DebugSolution** | Created for debugging solution-deployed processes. |
+| **Virtual** | Virtual folders (legacy). |
+
+### Process vs Release
+
+In the CLI, a "process" is what the Orchestrator API calls a "Release" -- a published automation package bound to a folder with runtime configuration. The CLI uses "process" consistently; the API uses "Release" in endpoint names and DTOs.
+
+### Job State Machine
+
+```
+Pending --> Running --> Successful
+                   --> Faulted
+                   --> Stopped
+
+Running --> Stopping --> Stopped
+Running --> Terminating --> Stopped
+Running --> Suspended <--> Resumed --> Running
+```
+
+Final states (`Successful`, `Faulted`, `Stopped`) are immutable. A stopped or faulted job cannot be restarted -- start a new job instead.
+
+### Folder-Scoped vs Tenant-Scoped Resources
+
+Some resources are **tenant-scoped** (machines, users, roles, packages, settings) -- they exist once per tenant and can be referenced from any folder. Others are **folder-scoped** (processes, jobs, assets, queues, triggers) -- they belong to a specific folder and require `--folder-path` or `--folder-key` on most operations.
+
+### Identifiers
+
+The CLI uses GUID keys for all entity references. Numeric IDs are never exposed to users. Folder arguments accept either a GUID key or a path string (e.g., `"Finance"` or `"Finance/Invoicing"`) -- the CLI resolves paths to keys internally.
+
+---
+
+## REST API Fallback
+
+When the CLI does not cover an operation, use the Orchestrator REST API directly with a stored token from `~/.uipath/.auth`.
+
+**Base URL pattern:**
+
+```
+${UIPATH_URL}/${UIPATH_ORG_NAME}/${UIPATH_TENANT_NAME}/orchestrator_/odata/
+```
+
+**Auth header:**
+
+```
+Authorization: Bearer <UIPATH_ACCESS_TOKEN>
+X-UIPATH-OrganizationUnitId: <FOLDER_ID>
+```
+
+Always check `uip or --help` and `uip resource --help` first -- most operations are covered by the CLI. Only fall back to REST when there is no CLI command for the operation you need.
+
+**Example -- list triggers (no CLI command yet):**
+
+```bash
+ACCESS_TOKEN=$(cat ~/.uipath/.auth | jq -r '.access_token')
+BASE_URL="https://cloud.uipath.com/myorg/mytenant/orchestrator_/odata"
+
+curl -s -G "${BASE_URL}/ProcessSchedules" \
+  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
+  -H "X-UIPATH-OrganizationUnitId: <FOLDER_ID>" | jq .
+```
+
+Token expiry: re-run `uip login` if you get a 401.
+
+---
+
+## Related
+
+- **Resources** (`uip resource`) — assets, queues, triggers, buckets, webhooks, libraries → [`uipath-resources`](../resources/resources.md)
+- **Solutions** (`uip solution`) — pack, publish, deploy solution packages → [`uipath-solution`](../solution/solution.md)

package/skills/uipath-platform/references/orchestrator/run-jobs.md

@@ -0,0 +1,332 @@
+# Run Jobs
+
+Upload automation packages, bind them as processes, start jobs, and monitor execution with logs, traces, and healing data.
+
+> For full option details on any command, use `--help` (e.g., `uip or jobs start --help`)
+
+## When to Use
+
+- Deploying and running automations end-to-end
+- Debugging failed or faulted jobs
+- CI/CD pipeline execution and verification
+- Monitoring long-running unattended processes
+
+## Prerequisites
+
+- Authenticated (`uip login`)
+- Target folder exists with machines assigned (see [setup-environment.md](setup-environment.md))
+- Automation package (.nupkg) built and ready to upload
+
+## Flow
+
+```mermaid
+graph LR
+    A[packages upload] --> B[processes create]
+    B --> C[jobs start]
+    C --> D[jobs logs]
+    C --> E[jobs traces]
+    C --> F[jobs healing-data]
+    C --> G[jobs history]
+```
+
+---
+
+## Step 1: Upload Package
+
+```bash
+uip or packages upload ./MyProcess.1.0.0.nupkg --output json
+
+# Target a custom feed instead of the tenant default
+uip or packages upload ./MyProcess.1.0.0.nupkg --feed-id <feed-key> --output json
+```
+
+## Step 2: Inspect Package
+
+Verify the upload and discover entry points before creating a process.
+
+```bash
+# Search for the uploaded package
+uip or packages list --search "MyProcess" --output json
+
+# List all versions of a package
+uip or packages versions <package-id> --output json
+
+# Inspect entry points (key format: PackageId:Version)
+uip or packages entry-points "MyProcess:1.0.0" --output json
+
+# Get one package version's full DTO (description, authors, target framework, ...)
+uip or packages get "MyProcess:1.0.0" --output json
+
+# Download the .nupkg back from the feed
+uip or packages download "MyProcess:1.0.0" --destination ./MyProcess.1.0.0.nupkg --output json
+```
+
+Entry points show which workflows inside the package can be executed. Multi-entry-point packages require `--entry-point` when creating a process.
+
+`packages get` accepts the `Id:Version` composite key returned by `packages list` / `packages versions`. The `--all-fields` flag returns the raw DTO including `tags`, `targetFramework`, `isCompiled`, etc.
+
+## Step 3: Create Process
+
+Bind the uploaded package to a folder as a runnable process:
+
+```bash
+# List published processes in a known folder path
+uip or processes list --folder-path "Production" --output json
+
+uip or processes create --name "MyProcess" \
+  --package-key "MyProcess" \
+  --package-version "1.0.0" \
+  --folder-path "Production" \
+  --output json
+```
+
+Key options:
+
+| Option | Description |
+|---|---|
+| `--entry-point <path>` | Required for multi-entry-point packages |
+| `--auto-update` / `--no-auto-update` | Auto-pick the latest package version on deploy |
+| `--job-priority <Low\|Normal\|High>` | Default execution priority |
+| `--specific-priority <1-100>` | Numeric priority override (mutually exclusive with `--job-priority`). Use when you need fine-grained ordering inside the same priority bucket. |
+| `--robot-size <Small\|Standard\|Medium\|Large>` | Cloud robot sizing for serverless runtimes |
+| `--input-arguments <json>` | Default input arguments (merged with per-job inputs) |
+| `--environment-variables <json>` | Default environment variables (merged with per-job env) |
+| `--tags <list>` | Comma-separated tags for filtering |
+| `--hidden-for-attended` / `--visible-for-attended` | Toggle visibility to attended robot users |
+| `--auto-create-triggers` / `--no-auto-create-triggers` | Auto-create connected triggers on deploy |
+| `--retention-period <days>` + `--retention-action <Delete\|Archive\|None>` (+ `--retention-bucket <id>`) | Job retention policy |
+| `--stale-retention-period <days>` + `--stale-retention-action <Delete\|Archive\|None>` | Stale-job retention policy |
+
+> The runtime kind (Unattended / Headless / NonProduction / AgentService / Serverless) is **not** a process-level setting; it's chosen per-job on `jobs start --runtime-type`. The process binds the package to a folder; runtime selection happens at execution time.
+
+#### Inspect / Edit / Roll back / Delete Processes
+
+```bash
+# Get one process by key (cross-folder; resolved through the release lookup)
+uip or processes get <process-key-guid> --output json
+
+# Validation report — what does the runtime see when it tries to start this process?
+# Returns missing tools, missing assets, missing connections, schema mismatches.
+uip or processes resources <process-key-guid> --output json
+
+# Edit fields after creation. Same flag set as `processes create` minus name/package-key/package-version,
+# plus --healing-agent / --no-healing-agent (Autopilot for Robots toggle).
+uip or processes edit <process-key-guid> --description "Updated description" --output json
+
+# Walk the package version history (every package version this release ever pointed at)
+uip or processes version-history <process-key-guid> --output json
+
+# Pin to a specific package version (typically used to roll back after a regression)
+uip or processes update-version <process-key-guid> --package-version 1.0.2 --output json
+
+# Roll back to the previous version recorded in version-history
+uip or processes rollback <process-key-guid> --output json
+
+# Delete the process (release). Package itself stays in the feed.
+uip or processes delete <process-key-guid> --output json
+```
+
+`processes edit` uses `Mapper.Map<ReleaseDto, UiRelease>(dto)` server-side, which means missing fields on the request body are nulled. The CLI works around this by spreading `currentRelease` as the baseline before applying overrides — but if you build the body yourself by hand, `tags`, `arguments`, `videoRecordingSettings`, `targetFramework`, `robotSize`, `resourceOverwrites`, `remoteControlAccess`, `targetRuntime`, `publisherLicense`, etc. will silently get nulled.
+
+## Step 4: Start Job
+
+Start execution from a process. The process key comes from `uip or processes list`.
+
+```bash
+uip or jobs start <process-key> --folder-path "Production" --output json
+
+# With input arguments and wait
+uip or jobs start <process-key> --folder-path "Production" \
+  --input-arguments '{"invoiceId": "INV-001", "amount": 1500}' \
+  --wait-for-completion --timeout 600 \
+  --output json
+```
+
+Key options:
+
+- `--input-arguments <json>` / `--input-file <path>` — pick one. `--input-arguments` inlines a JSON object; `--input-file` uploads a file as the job's `InputFile` argument.
+- `--attachment <[name=]path>` — upload one or more files and attach them to the job. Repeat the flag for multiple. Pair with `--attachment-id <guid>` to reuse an attachment that was previously uploaded.
+- `--runtime-type <type>` — `Unattended`, `Headless`, `NonProduction`, `AgentService`, or `Serverless`. Picks the runtime kind the scheduler will use.
+- `--strategy <strategy>` — `ModernJobsCount` (default; spawn N independent jobs, paired with `--jobs-count`), `All` (run on every available robot in the folder), `Specific` (use `--user-keys` / `--machine-keys`).
+- `--user-keys <guids>` / `--machine-keys <guids>` — comma-separated GUIDs to pin the job to specific identities. With `--strategy ModernJobsCount` they restrict the candidate pool; with `Specific` they're required.
+- `--healing-agent` — enable Autopilot for Robots (Healing Agent) just for this job, regardless of the process-level `--healing-agent` setting on `processes edit`. Useful for one-off self-healing without flipping the process default.
+- `--reference <text>` — user-set reference (free-form string) attached to the job. Useful for correlation with external systems.
+- `--environment-variables <json>` — JSON object of per-job environment variables. Merged on top of folder-/process-level env.
+- `--run-as-me` — run under the caller's identity instead of resolving an unattended robot account in the folder.
+- `--wait-for-completion` + `--timeout <seconds>` (default 300) + `--poll-interval <seconds>` (default 5) — poll until the job reaches a terminal state.
+- `--output-dir <path>` + `--no-download` — when `--wait-for-completion` is set, the CLI downloads the job's `OutputFile` to this directory automatically. Pass `--no-download` to opt out.
+- `--job-priority <Low|Normal|High>` — execution priority on the runtime queue.
+
+## Step 5: Monitor Job
+
+Check job status. `jobs get` is cross-folder -- no `--folder-path` needed:
+
+```bash
+# Get a specific job by key
+uip or jobs get <job-key> --output json
+
+# List running jobs in a folder
+uip or jobs list --state Running --folder-path "Production" --output json
+
+# Filter by process name and date range
+uip or jobs list --process-name "MyProcess" --folder-path "Production" --output json
+```
+
+## Step 6: Get Logs
+
+```bash
+uip or jobs logs <job-key> --output json                  # All logs
+uip or jobs logs <job-key> --level Error --output json    # Error logs only
+uip or jobs logs <job-key> --export --destination ./logs.csv  # Export to CSV file
+```
+
+`--export` writes a CSV file instead of terminal output. Combine with `--destination` (or `-d`) to set the file path. Logs are cross-folder -- no `--folder-path` required.
+
+## Step 7: Get Traces
+
+Retrieve LLM and agentic execution traces for Agent-type processes:
+
+```bash
+uip or jobs traces <job-key> --output json
+```
+
+Traces are only available for processes that use UiPath Autopilot or Agent capabilities. For deeper span-level data, use `uip traces spans get [trace-id]` (or `uip traces spans get --job-key <key>`) — see [traces.md](../traces/traces.md).
+
+Traces are cross-folder -- no `--folder-path` required.
+
+## Step 8: Get Healing Data
+
+Download Autopilot recovery data (screenshots + UI element data) as a ZIP:
+
+```bash
+uip or jobs healing-data <job-key> -o ./healing-data.zip
+```
+
+The ZIP contains screenshots and UI metadata from Autopilot self-healing attempts.
+
+## Step 9: Job History
+
+View the state transition timeline (e.g., Pending -> Running -> Faulted) with timestamps:
+
+```bash
+uip or jobs history <job-key> --output json
+```
+
+## Step 10: Stop, Restart, Resume
+
+Control running or suspended jobs:
+
+```bash
+# Stop a running job
+uip or jobs stop <job-key> --strategy SoftStop --output json
+
+# Force-kill a job
+uip or jobs stop <job-key> --strategy Kill --output json
+
+# Restart a faulted or stopped job
+uip or jobs restart <job-key> --output json
+
+# Resume a suspended job with new input
+uip or jobs resume <job-key> --input-arguments '{"approved": true}' --output json
+```
+
+## Step 11: Manage Processes
+
+Update, rollback, or edit processes after deployment:
+
+```bash
+# Update to a newer package version
+uip or processes update-version <process-key> --output json
+
+# Rollback to previous version
+uip or processes rollback <process-key> --output json
+
+# Edit process properties
+uip or processes edit <process-key> --output json
+```
+
+---
+
+## Complete Example
+
+```bash
+# Upload -> create process -> start job -> check logs
+uip or packages upload ./InvoiceProcessor.1.0.0.nupkg --output json
+uip or packages entry-points "InvoiceProcessor:1.0.0" --output json
+
+uip or processes create --name "InvoiceProcessor" \
+  --package-key "InvoiceProcessor" --package-version "1.0.0" \
+  --folder-path "Finance" --job-priority Normal \
+  --output json
+
+uip or jobs start <process-key> --folder-path "Finance" \
+  --input-arguments '{"batchDate": "2026-04-22"}' \
+  --wait-for-completion --timeout 600 --output json
+
+uip or jobs logs <job-key> --level Error --output json
+uip or jobs logs <job-key> --export --destination ./invoice-logs.csv
+```
+
+---
+
+## Variations and Gotchas
+
+### "Process" vs "Release"
+
+The CLI uses "process" but the Orchestrator API calls this entity a "Release". They are the same thing. When reading API docs, `ReleaseKey` = process key from `uip or processes list`.
+
+### Process Key vs Package Key
+
+These are different identifiers:
+
+| Key | Source | Format |
+|-----|--------|--------|
+| Process key | `uip or processes list` | GUID (e.g., `a1b2c3d4-...`) |
+| Package key | `uip or packages list` | String ID (e.g., `InvoiceProcessor`) |
+| Package download key | `uip or packages download` | `PackageId:Version` (e.g., `InvoiceProcessor:1.0.0`) |
+
+### Job States
+
+Jobs progress through these states:
+
+```
+Pending -> Running -> Successful
+                   -> Faulted
+                   -> Stopped
+                   -> Suspended (awaiting input)
+```
+
+Final states (Successful, Faulted, Stopped) are frozen -- no further transitions occur.
+
+### Wait and Input Behavior
+
+- `--wait-for-completion` polls at `--poll-interval` (default 5s) until a final state or `--timeout` (default 300s)
+- `--input-arguments` accepts JSON; `--input-file` reads from a file path
+- If JSON exceeds 10K characters, the CLI automatically offloads it to an InputFile (server-side)
+- Use `uip or packages entry-points` to discover expected argument names and types
+
+### Cross-Folder Commands
+
+These commands resolve the folder from the job key -- no `--folder-path` needed:
+
+- `uip or jobs get <key>`
+- `uip or jobs logs <key>`
+- `uip or jobs traces <key>`
+- `uip or jobs history <key>`
+- `uip or jobs healing-data <key>`
+
+### Package Download
+
+To download a package .nupkg, use the `PackageId:Version` format:
+
+```bash
+uip or packages download "MyProcess:1.0.0" --destination ./packages/ --output json
+```
+
+---
+
+## Related
+
+- [setup-environment.md](setup-environment.md) — Folder creation, machine assignment, user setup
+- [traces.md](../traces/traces.md) — Deep-dive into LLM/agentic traces and spans
+- Resources (assets, queues, buckets, triggers, webhooks, libraries) → [`uipath-resources`](../resources/resources.md)