uip agent push / pull

uip agent push and uip agent pull are the two halves of the Studio Web round-trip. They share the same transport format (.uis, a ZIP archive of the agent project), the same authentication model, and the same error surface. Use push to send a local project to Studio Web so it shows up in the Agent Builder UI; use pull to download a solution from Studio Web as a .uis you can inspect, extract, or pack back into an Orchestrator deployment.

Both verbs require an active CLI session (uip login).

All subcommands honor the global options (--output, --output-filter, --log-level, --log-file). Exit codes follow the standard contract.

---

uip agent push

Import an agent project into Studio Web as a new solution, or overwrite an existing solution.

When the input is a directory, push validates the project structure, runs the Studio Web schema validation pass (unless --skip-schema-validation), packs to a temporary .uis excluding .agent-builder/, and posts the archive to the Studio Web Solution Import API. When the input is already a .uis, the archive is uploaded as-is.

On a successful directory push, SolutionStorage.json at the project root is updated with the returned cloud solution and project IDs — subsequent uip agent eval run invocations can use those IDs without you passing --solution-id.

Synopsis

uip agent push [path] [-n <name>] [--overwrite <solutionId>] [--skip-schema-validation] [--login-validity <minutes>]

Arguments

• [path] (optional, default .) — Path to the agent project directory or a .uis file.

Options

Drapeau	Default	Objectif
-n, --name <name>	agent metadata.name → path basename	Solution name in Studio Web.
--overwrite <solutionId>	—	Overwrite an existing solution by ID instead of creating a new one. Changes the endpoint from POST /api/Solution/Import to POST /api/Solution/<id>/Overwrite.
--skip-schema-validation	off	Skip the Studio Web schema validation pass. Directory inputs only — a .uis input never runs schema validation.
--login-validity <minutes>	10	Minimum minutes of token validity required.

Exemples

# Push the current directory as a new solution
uip agent push

# Push a specific directory
uip agent push ./my-agent

# Overwrite an existing solution in place
uip agent push ./my-agent --overwrite a1b2c3d4-0000-0000-0000-000000000001

# Push a pre-packed archive
uip agent push ./dist/my-agent.uis

Data shape (--output json)

{
  "Code": "AgentPush",
  "Data": {
    "Status": "Agent imported into Studio Web",
    "Name": "my-agent",
    "SolutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ProjectCount": 1,
    "CloudProjectId": "a1b2c3d4-0000-0000-0000-000000000002"
  }
}

With --overwrite, Status is "Solution overwritten successfully" and SolutionId echoes the value you passed. CloudProjectId is "-" if the response does not include a projects array.

---

uip agent pull

Download a solution from Studio Web as a .uis archive. Optionally extract the archive into a sibling directory.

Synopsis

uip agent pull <solutionId> [-d <dir>] [-n <name>] [--extract] [--login-validity <minutes>]

Arguments

• <solutionId> (required) — Solution UUID. Get one from uip agent list.

Options

Drapeau	Default	Objectif
-d, --destination <dir>	.	Destination directory for the downloaded file. Created if needed.
-n, --name <name>	<solutionId>	Output filename (extension-less). .uis is appended if not present.
--extract	off	After download, extract the .uis into a same-named directory alongside it.
--login-validity <minutes>	10	Minimum minutes of token validity required.

Exemples

# Download by ID into the current directory
uip agent pull a1b2c3d4-0000-0000-0000-000000000001

# Download into a specific directory
uip agent pull a1b2c3d4-0000-0000-0000-000000000001 -d ./downloads

# Download with a friendly filename and extract
uip agent pull a1b2c3d4-0000-0000-0000-000000000001 \
  -d ./downloads \
  -n invoice-agent \
  --extract

Data shape (--output json)

{
  "Code": "AgentPull",
  "Data": {
    "Status": "Solution exported successfully",
    "SolutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Output": "/abs/path/downloads/a1b2c3d4-0000-0000-0000-000000000001.uis"
  }
}

With --extract, the payload additionally includes ExtractedTo: "/abs/path/downloads/<name>".

---

Round-trip example

# Iterate locally, push to Studio Web, edit in the UI, pull back
uip agent init ./my-agent
uip agent validate ./my-agent
uip agent push ./my-agent               # captures SolutionId

# (edit in Studio Web)

uip agent pull <SolutionId> -d ./downloads --extract
# compare ./my-agent with ./downloads/<SolutionId>/ to reconcile

Related

• uip agent list — enumerate solution IDs to feed into pull.
• uip agent pack — produce a .uis without involving Studio Web.
• uip agent validate — run before push to avoid server-side rejections.
• uip agent share — share a solution after push.

Voir également

• Authentication — sessions and --login-validity.
• Concepts: skills — how an imported solution's entry points become skills.
• Global options, Exit codes.