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, libraries, tests, agent projects, API workflows) into a single deployable unit.

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 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 npm install -g @uipath/cli, then uip login, and abort the work until those succeed.

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. 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.

Reference Navigation

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.