uipath-solution

UiPath Solution — uip solution lifecycle

Create, pack, publish, deploy, and manage UiPath Solution packages (.uipx) via the uip solution CLI surface. A Solution bundles multiple automation projects (processes, tests, agent projects, API workflows) into a single deployable unit. A library is not one of them — it is published on its own and at most declared as a Library resource (Develop a Solution § Step 2).

Use the CLI. Don't roll your own REST for solution ops. Hand-rolling HTTP calls misses the X-UIPATH-OrganizationUnitId folder header, OData filter shape, pagination envelope, pipelinesInstall deploy semantics, retry behavior, and the Result/Code/Data output contract. The CLI is the source of truth.

Platform support. Solutions runs on Automation Cloud and on self-hosted Automation Suite from 2.2510.0 onward; not on Standalone Orchestrator. Available project types vary by AS version (Maestro self-hosted only from 2.2510.2). Compat matrix + project-type-by-version table → Solution Overview — Platform availability.

When to Use This Skill

• User has a .uipx solution and wants to pack / publish / deploy / activate / upload

• User wants to create a new solution (uip solution init), add or remove projects, or refresh solution resources

• User wants to work on a solution that already exists in Studio Web, or move one to another org or tenant — start with uip solution download (Start From an Existing Solution)

• User asks to set up a CI/CD pipeline that builds, publishes, and deploys a UiPath solution
• User mentions deploy configs, environment promotion, or activating a deployed solution

• A skill or main agent detected a .uipx file and redirected the user here

Skip this skill when:

• The task is PDD → SDD architecture/design (sdd.md / pdd.md) — load uipath-planner.
• The deployable is a single non-solution package (e.g., a one-off RPA library or coded app) — those use uip rpa publish / uip codedapp publish and route through uipath-platform or the relevant specialist.
• The task is non-solution Orchestrator work (folders, jobs, assets, queues, IS connections) — load uipath-platform.

CLI Surface Probe

Before the first uip solution … command in a session, probe the solution surface to detect pre- vs post-rename CLI:

uip solution init --help --output json

• Result Success → post-rename CLI (default). Use the commands and flags as documented in the references.
• unknown command / non-zero exit → pre-rename CLI. Translate via the table below before each call. Re-probe on any later unknown command error.

• command not found / uip: not found / 'uip' is not recognized → CLI not installed. Tell the user to run the official installer (curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash on macOS/Linux; irm https://download.uipath.com/uipath-cli/install.ps1 | iex in Windows PowerShell), then uip login, and abort the work until those succeed.

Post-rename (default)	Pre-rename equivalent
uip solution init <NAME>	uip solution new <NAME>
uip solution deploy run --parent-folder-path <PATH>	uip solution deploy run --folder-path <PATH>
uip solution deploy run --parent-folder-key <KEY>	uip solution deploy run --folder-key <KEY>
uip solution projects <VERB>	uip solution project <VERB> (singular still works post-rename, but is hidden and deprecated)
uip solution resources <VERB>	uip solution resource <VERB>
uip solution projects import <PATH>	uip solution project import --source <PATH>

All other solution subcommands (pack, publish, deploy activate/status/uninstall, upload, resources …, projects add/remove/list) are unchanged on both surfaces.

Critical Rules

1. Probe the CLI surface before the first uip solution command in a session. Run uip solution init --help --output json. Success = post-rename CLI (default); unknown command = pre-rename CLI — translate via the fallback table above. Re-probe on any later unknown command error.

2. Always use --output json for uip solution commands whose output you parse. JSON is compact and stable; the default for non-interactive runs.
3. Use the CLI, never roll your own REST for solution operations. Hand-rolled HTTP calls miss the X-UIPATH-OrganizationUnitId header, OData filter shape, pagination envelope, and pipelinesInstall deploy semantics. Only fall through to REST after confirming no uip solution command covers the task.
4. Never hand-edit resources/solution_folder/. It's auto-generated by uip solution projects add / import and auto-cleaned by projects remove. Manual edits desync from .uipx and produce silent failure modes. See scenarios/manual-edits.md.
5. .uipx and resources/solution_folder/ must always agree on the project set. Diffing them is the fastest way to detect corrupted state. If they disagree, fix via uip solution projects add/remove — never by editing either side directly.
6. Run uip solution resources refresh before pack or upload. Bundled artefact files and userProfile/<userId>/debug_overwrites.json must reflect current cloud state. Skipping refresh ships stale bindings.
7. AppV2 coded apps register in .uipx when authored inside a solution. uip codedapp init is the solution-side scaffolding entry point — run it from inside a .uipx solution. It writes project.uiproj (ProjectType: "AppV2") + webAppManifest.json, nests source under source/dist/, and auto-registers as Type: "AppV2" — emitting resources/solution_folder/app/{Coded,CodedAction}/. uip solution projects add / uip solution projects import cover existing AppV2 folders too — both read webAppManifest.config.isActionApp to pick Coded / CodedAction subType (defaults Coded for legacy folders with no manifest). uip solution pack bundles them; uip solution deploy run provisions them. Standalone coded apps are a different lifecycle — scaffold them with npx create-vite@latest (not uip codedapp init), keep a flat dist/ at the project root, and deploy via uip codedapp pack → uip codedapp publish → uip codedapp deploy. See /uipath:uipath-coded-apps.
8. Verify the artifact after every CLI mutation. Read project.json, .uipx, or uip solution deploy status output — exit codes lie. Verification is additional; it does not replace requested read-only list commands. If the user asks to show or list registered projects, solution resources, packages, deployments, or statuses, run the matching uip solution ... list/status --output json command and then inspect files only as a secondary sanity check.
9. A deployment in Draft is a failed deploy, not a pending one. Validation rejected a resource and the install never completed; it never advances on its own and cannot be activated. Read the reasons — Validation: / Conflicts: land in the failure's Instructions on every feed, since each deploy waits for its run — fix them with deploy config set / link, and rerun deploy run --config-file <file> with the same --name and --package-version. While the draft exists it owns the deployment: any other version is refused, deploy upgrade included, until the draft is finished that way or discarded (deploy upgrade <draft-key> --discard-draft, or Delete draft in Orchestrator). To look at it, run deploy list with the same feed flag, which is tenant-scoped without one and shows no Personal Workspace or folder-feed row at all. See A deploy that stops in Draft.
10. Replacing an installed resource with a link needs explicit consent. When a deploy run config file (deploy config link) or the new version in a deploy upgrade links a resource the deployment already installed, the server deletes the installed copy and its data. Newer servers ask first, and newer CLI builds then stop with Deploying '<name>' will permanently delete … installed resource(s) replaced by links: <kind> '<name>', … (Upgrading … for deploy upgrade; ErrorCode: invalid_argument, the resources also in Data.PermanentDeletionResources). Nothing was installed and the attempt is kept as a pending draft. This is not a config error to fix: confirm only if the user wants those copies and their data gone, then re-run the same command with --acknowledge-permanent-deletion — on deploy upgrade never with --discard-draft, which drops the very links being confirmed. To keep the copies instead, deploy config unlink <file> <resource> and re-run (deploy run), or deploy upgrade <draft-key> --discard-draft (deploy upgrade). --yes is not this consent. See Replacing an installed resource with a link.
11. Never pass --force to deploy uninstall on your own. It sends forceUninstall: true, which abandons uncompleted jobs and permanently deletes installed resources that were replaced by links, with their data (it also stands in for --yes). When an uninstall fails with Message "…this deployment has uncompleted jobs; --force uninstalls anyway" or "…permanently deletes these resources and their data: '', …" (Data.JobsNotInFinalState, Data.PermanentDeletionResources, Retry: RetryWillNotFix), show the user the cause and add --force only when they explicitly accept it. Never add it to get past "…errors that --force cannot get past" (Retry: RetryLater): resolve that in Orchestrator and re-run without --force. See When the uninstall is refused.
12. For multi-environment promotion, switch tenants with uip login tenant set <tenant> and pass a per-environment deploy config via --config-file <path>. The same packed .uipx deploys to dev/staging/prod — the environment differs by the target tenant and the config file (generated with deploy config get, edited with config set / config link), not by a different package. There is no -c <CONFIG_KEY> flag.

Workflow

The typical lifecycle for a UiPath Solution:

1. init / project add  → Create solution, register projects (.uipx + resources/solution_folder/)
2. resources refresh   → Sync bundled artefacts and debug overwrites with cloud state
3. (optional) restore  → Resolve NuGet deps in place (incl. authenticated Orchestrator feeds); login first
4. pack                → Produce deployable .zip package
5. login               → uip login (if not already authenticated)
6. publish             → Upload packed solution to UiPath
7. deploy run          → Promote to Orchestrator (auto-activates by default)
8. (optional) activate → Use --skip-activate on deploy, then activate explicitly

restore is an optimization, not a requirement. pack restores dependencies internally, so a separate restore step is only useful when you want deps resolved up front — most often in CI (login → restore → pack) to fail fast on a missing feed before the heavier pack runs. restore takes a <solutionPath> only (solution dir with a .uipx, or a .uis file), resolves deps in place, and does not produce a package. It needs an authenticated session to reach private Orchestrator feeds, so run uip login before it.

AppV2 coded apps in the solution flow through uip solution, not uip codedapp directly. When a coded-app project has Type: "AppV2" in .uipx, uip solution pack bundles its .nupkg and uip solution deploy run provisions it in the deployment folder — no separate uip codedapp pack / publish / deploy step. Standalone coded apps (scaffolded outside any solution via npx create-vite, flat dist/ at the project root, no project.uiproj / webAppManifest.json) use the direct codedapp path instead. See uipath-coded-apps for the standalone lifecycle and for authoring an AppV2 project inside a solution via uip codedapp init.

Two distinct distribution paths from the same source:

• pack → publish → deploy run — promotes a versioned package to Orchestrator.
• upload — pushes the solution to Studio Web for browser-based debugging only. Does not produce a published package and cannot be deployed via deploy run.

Authentication is a prerequisite. Check uip login status --output json before any work; if not logged in, ask the user to run uip login (interactive browser flow). See uipath-platform for full auth options (interactive OAuth, client credentials, tenant switching).

This skill is the terminal step of an SDD-driven build: after uipath-planner produces the SDD and derives the task list, and implementation specialists build the projects, the .uipx is packed and shipped here.

Start From an Existing Solution

When the solution already exists in Studio Web, download its source instead of recreating it:

uip solution download <solution-id> --destination <dir> --extract --output json

• <solution-id> is the Studio Web solution GUID. Ask the user for it when they have not given it.
• Work inside Data.ExtractedTo. It holds the .uipx and the project folders. Read the AGENTS.md / CLAUDE.md there first; --extract adds them when the archive has none. Extract into a new or empty folder: --extract writes over existing files, so re-running it on a copy you have edited loses those edits. Confirm with the user first.
• The extracted .uipx keeps the Studio Web SolutionId, and uip solution upload overwrites the solution that has that id in the org you are logged into, or imports a new one when there is none (Develop a Solution § upload). To move the solution to another org or tenant, log in there and upload it, or pack → publish → deploy run there.

Reference Navigation

File	Purpose
Solution Overview	What a Solution is, .uipx manifest, file structure, lifecycle diagram, command tree

| Develop a Solution | uip solution init / project add / import / remove / resources refresh / resources add / resources remove / resources edit; field-tested gotchas |

| Pack and Deploy | restore / pack / publish / deploy run / feeds list, targeting a non-tenant feed (--feed / --personal-workspace), deploy configs, CI/CD pipeline patterns | | Activate and Manage | deploy activate / status / upgrade / uninstall / delete, in-place version upgrades, environment management | | Scenarios Index | Failure modes and edge cases — manual edits, shared resources, virtual resources, name collisions |

Anti-patterns

1. Hand-rolling REST calls for pack, publish, deploy run, or activate. The uip solution CLI handles auth, folder headers, pipeline semantics, and pagination correctly. Reach for REST only after confirming no command covers the task.
2. Editing resources/solution_folder/ directly. It is auto-generated and auto-cleaned. Manual edits desync from .uipx. Use uip solution projects add/remove instead.
3. Skipping uip solution resources refresh before pack or upload. Ships stale bindings and debug-overwrite state.
4. Running uip codedapp pack / publish / deploy on an AppV2 project that's already registered in .uipx. Once registered as Type: "AppV2", the coded app is part of the solution — uip solution pack / uip solution publish / uip solution deploy run handle it. Direct uip codedapp publish bypasses the solution's deploy config (external client ID, routing name, action schema) and creates a duplicate registration. Use uip codedapp directly only for standalone coded apps scaffolded with npx create-vite (no .uipx in the tree, no project.uiproj / webAppManifest.json).
5. Creating a new .uipx per environment instead of using deploy configs. One packed solution promotes to dev/staging/prod via a per-environment --config-file (and uip login tenant set to target the tenant). Different .uipx files per environment defeats version tracking.
6. Using uip solution upload (Studio Web) as a deployment path. Upload is for browser-based debugging only — it does not produce a published package and cannot be promoted via deploy run. Use pack → publish → deploy run for real deploys. upload also lands the solution in Studio Web's Cloud workspace tab — not the Local tab; SW's Local tab is a separate registration not addressable by uip solution.
7. Trusting exit codes alone after a mutation. Always read the artefact (project.json, .uipx, deploy status) — a non-zero exit may indicate partial state and a zero exit can mask warnings.