uipath-solution

name	uipath-solution
description	Always invoke for `.uipx` files. UiPath Solution lifecycle via the `uip solution` CLI: init/restore/pack/publish/deploy/activate/upload, project add|import|remove, resource refresh|add|remove|edit. Also DIAGNOSE solution-lifecycle failures: pack/publish/deploy/activate errors, stale or missing bindings, unimported/unset/unresolved resources, deploy error codes (e.g. `[1009] Invalid argument 'Value'`), publish name+version/processKey collisions, and `uip solution` 'unknown command' after the new→init rename. Bundles multiple automation projects (RPA/Flow/Case/Agents/API Workflows) into one deployable `.uipx`. For PDD→SDD design (sdd.md/pdd.md) & multi-skill task derivation→uipath-planner. For non-solution Orchestrator/IS/resources/auth/traces→uipath-platform. For .xaml/.cs→uipath-rpa. For .flow→uipath-maestro-flow. For .bpmn→uipath-maestro-bpmn. For agent.json and .py agents→uipath-agents. For coded-app deploy→uipath-coded-apps.
when_to_use	User mentions .uipx / 'uip solution' / 'pack the solution' / 'publish the solution' / 'deploy the solution' / 'activate' / multi-project / Solution scope / Solution Folder. Fires for 'create a new solution', 'add project/resource to solution', 'add a queue/asset/bucket/connection to the solution', 'import a cloud queue/asset', 'edit/remove a resource', 'change a queue/asset field', 'set an asset value in the solution'. Also fires to DIAGNOSE solution problems: 'why did my solution pack/publish/deploy fail', 'pack ships stale/old bindings', 'my resource edit didn't take effect', 'refresh imported 0 bindings', deploy fails '[1009] Invalid argument Value', publish 'name+version / processKey collision', 'uip solution new: unknown command', 'coded app missing from the .uipx / not packed'. (Solution build-time/CLI faults belong here; faulted Orchestrator JOBS at runtime → uipath-troubleshoot.) Load BEFORE editing .uipx or running uip solution commands. For PDD→SDD design→uipath-planner; for an 'architect then deploy' two-phase request, run uipath-planner first, then return here to pack/deploy.

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

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 / resources refresh / resources add / resources remove / resources edit; field-tested gotchas
Pack and Deploy	restore / 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 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.