# uip agent pack

> `uip agent pack` bundles a local agent project into a `.uis` file. A `.uis` is a plain ZIP archive of the project tree; it is the transport format accepted by Studio Web (`uip agent push`) and the input to the Orchestrator publishing flow (`uip agent publish`).

`uip agent pack` bundles a local agent project into a `.uis` file. A `.uis` is a plain ZIP archive of the project tree; it is the transport format accepted by Studio Web (`uip agent push`) and the input to the Orchestrator publishing flow (`uip agent publish`).

Before packing, the command:

1. Validates the project structure (`agent.json`, `entry-points.json`, `project.uiproj`, resource tree).
2. Runs the Studio Web schema validation pass (unless `--skip-schema-validation` is set). Any non-fatal warnings are surfaced; any fatal issue aborts the pack with a `Schema validation failed` error.

The produced archive excludes `.agent-builder/` (local-development scaffolding that Studio Web regenerates on import).

## Synopsis

```
uip agent pack [path] [-d <dir>] [-n <name>] [--skip-schema-validation]
```

All `uip agent pack` invocations honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## Arguments

- `[path]` *(optional, default `.`)* — Path to the agent project directory.

## Options

| Flag | Default | Purpose |
|---|---|---|
| `-d, --destination <dir>` | `.` | Destination directory for the `.uis` file. Created if it does not exist. |
| `-n, --name <name>` | *agent `metadata.name`* → project dir basename | Package name. The output file is `<name>.uis`. |
| `--skip-schema-validation` | off | Skip the Studio Web schema validation pass. Useful for inspecting work-in-progress projects that would be rejected by the live API; do not use in a release pipeline. |

## Examples

```bash
# Pack the current directory into ./my-agent.uis
uip agent pack

# Pack a specific project into ./dist/my-agent.uis
uip agent pack ./my-agent -d ./dist

# Override the archive name
uip agent pack ./my-agent -d ./dist --name invoice-agent-v1

# Skip schema validation to pack a work-in-progress project
uip agent pack ./my-agent --skip-schema-validation
```

## Data shape (--output json)

```json
{
  "Code": "AgentPack",
  "Data": {
    "Status": "Agent packed successfully",
    "Name": "my-agent",
    "Output": "/abs/path/dist/my-agent.uis"
  }
}
```

Warnings emitted during schema validation are logged separately (`Warning` entries) and do not appear in the success `Data`. Fatal schema errors fail the command before the archive is written.

## Relationship to publish

`uip agent publish` runs its own pack/migrate/repack pipeline internally; you do not need to run `pack` first if your next step is `publish`. Use `pack` when you want:

- A `.uis` you can hand-inspect (rename to `.zip` and unzip).
- A `.uis` you plan to push to Studio Web via `uip agent push <file.uis>`.
- A deterministic local archive as an artifact in a CI job.

## Related

- [`uip agent validate`](./uip-agent-validate.md) — run the migration pipeline before packing.
- [`uip agent publish`](./uip-agent-publish.md) — pack and push the package to Orchestrator in one step.
- [`uip agent push`](./uip-agent-push-pull.md#uip-agent-push) — import a packed project into Studio Web.

## See also

- [Global options](./global-options.md), [Exit codes](./exit-codes.md).