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.

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.

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>

All other solution subcommands (pack, publish, deploy activate/status/uninstall, upload, resource …, project add/import) 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 project add / import and auto-cleaned by project 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 project 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. Coded apps are NOT registered in .uipx. uip solution project add does not apply to coded-app directories; they deploy independently via uip codedapp publish / deploy. A coded app folder can sit alongside a solution but is not part of its manifest.
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, the deploy config (-c <CONFIG_KEY>) is the environment selector. Same .uipx deploys to dev/staging/prod via different config keys, not different packages.

Workflow

The typical lifecycle for a UiPath Solution:

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

Coded apps in the project list deploy in parallel, not through uip solution. Coded-app projects (Coded Web Apps and Coded Action Apps) have no project.uiproj / project.json and are NOT registered via uip solution project add. For each coded-app project in the unified list, run uip codedapp publish / uip codedapp deploy independently — the rest of the solution still goes through steps 1-7 above. See uipath-coded-apps for the coded-app lifecycle.

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

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 / resource refresh / resource add / resource remove / resource edit; field-tested gotchas
Pack and Deploy	pack / publish / deploy run, deploy configs, CI/CD pipeline patterns
Activate and Manage	deploy activate / status / uninstall, 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 project add/remove instead.
3. Skipping uip solution resources refresh before pack or upload. Ships stale bindings and debug-overwrite state.
4. Adding a coded-app directory via uip solution project add. Coded apps have no project.uiproj / project.json and are not packed by uip solution pack. Deploy them independently via uip codedapp publish / deploy.
5. Creating a new .uipx per environment instead of using deploy configs. One solution package promotes to dev/staging/prod via different -c <CONFIG_KEY> values. 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.