# uip agent list / share

> Syntax and options for `uip agent list` and `uip agent share`, which enumerate and manage access to Studio Web solutions.

`uip agent list` and `uip agent share` both operate on Studio Web **solutions** — the cloud-side representation of an agent project. `list` enumerates solutions visible to the current user; `share` manages user and group access to a single solution. They are grouped here because both are pure Studio Web management verbs, distinct from the file-level operations in `uip agent file` and from the Orchestrator-side operations in `deploy` / `run`.

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

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

---

## uip agent list

List solutions from Studio Web, optionally filtered by a keyword.

### Synopsis

```
uip agent list [-s <query>] [-l <n>] [--login-validity <minutes>]
```

### Arguments

None.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `-s, --search <query>` | — | Keyword filter applied to the Studio Web `SearchSolutionsAndProjects` endpoint. |
| `-l, --limit <n>` | `20` | Maximum number of results. Sent as the `pagingOptions.limit` query parameter. |
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

#### Examples

```bash
# Simplest — list up to 20 solutions
uip agent list

# Filter by keyword
uip agent list --search invoice

# Page through larger result sets
uip agent list --limit 100
```

### Data shape (--output json)

```json
{
  "Code": "AgentList",
  "Data": [
    {
      "Name": "Email Triage",
      "Id": "a1b2c3d4-0000-0000-0000-000000000001",
      "Status": "Completed",
      "PublishStatus": "Published",
      "LastModified": "2025-04-10T14:30:00Z",
      "Projects": 2
    }
  ]
}
```

Empty result sets produce `Data: { "Message": "No solutions found" }` instead of an empty array. `Projects` is the count of projects nested inside the solution, not a listing.

---

## uip agent share

Manage user and group access to a Studio Web solution. Three subcommands: `add`, `list`, and `remove`.

### Synopsis

```
uip agent share add    <solutionId> <entityId> [--permission <perm>] [--group] [--login-validity <minutes>]
uip agent share list   <solutionId>                                   [--login-validity <minutes>]
uip agent share remove <solutionId> <entityId>                        [--group] [--login-validity <minutes>]
```

### uip agent share add

Grant access to a user or group.

#### Arguments

- `<solutionId>` *(required)* — Solution UUID.
- `<entityId>` *(required)* — User or group UUID.

#### Options

| Flag | Default | Purpose |
|---|---|---|
| `--permission <perm>` | `write` | Permission level. One of: `none`, `read`, `write`, `publish`, `readWritePublish`. Case-insensitive; invalid values fail with a validation error. |
| `--group` | off (user) | Treat `<entityId>` as a group instead of a user. |
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

#### Examples

```bash
# Grant write access to a user
uip agent share add \
  a1b2c3d4-0000-0000-0000-000000000001 \
  a1b2c3d4-0000-0000-0000-000000000501 \
  --permission write

# Grant read-only access to a group
uip agent share add <solutionId> <groupId> --permission read --group

# Full access (read + write + publish)
uip agent share add <solutionId> <userId> --permission readWritePublish
```

#### Data shape (`--output json`)

```json
{
  "Code": "AgentShare",
  "Data": {
    "Status": "Solution shared successfully",
    "SolutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "SharedWith": "a1b2c3d4-0000-0000-0000-000000000501",
    "IsGroup": false,
    "Permission": "write"
  }
}
```

### uip agent share list

List users and groups with access to a solution.

#### Arguments

- `<solutionId>` *(required)* — Solution UUID.

#### Options

Only `--login-validity`.

#### Example

```bash
uip agent share list a1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape (`--output json`)

```json
{
  "Code": "AgentShareList",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000501",
      "Name": "Jane Doe",
      "Email": "jane@example.com",
      "IsGroup": false,
      "Permission": "write"
    }
  ]
}
```

An empty response returns `Data: { "Message": "No sharing permissions found for this solution" }`.

### uip agent share remove

Revoke a user or group's access.

#### Arguments

- `<solutionId>` *(required)* — Solution UUID.
- `<entityId>` *(required)* — User or group UUID.

#### Options

| Flag | Default | Purpose |
|---|---|---|
| `--group` | off (user) | Treat `<entityId>` as a group instead of a user. |
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

#### Example

```bash
uip agent share remove a1b2c3d4-0000-0000-0000-000000000001 a1b2c3d4-0000-0000-0000-000000000501
```

#### Data shape (`--output json`)

```json
{
  "Code": "AgentShareRemove",
  "Data": {
    "Status": "Access removed successfully",
    "SolutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "RemovedEntity": "a1b2c3d4-0000-0000-0000-000000000501"
  }
}
```

---

## Related

- [`uip agent push`](./uip-agent-push-pull.md#uip-agent-push) — import a project and obtain the `SolutionId` you use here.
- [`uip agent pull`](./uip-agent-push-pull.md#uip-agent-pull) — download a solution listed by `list`.
- [`uip agent file`](./uip-agent-file.md) — list, download, and upload files inside a solution's projects.

## See also

- [Authentication](./authentication.md) — sessions, tenants, and `--login-validity`.
- [Global options](./global-options.md), [Exit codes](./exit-codes.md).