# uip agent file

> `uip agent file` operates on the individual files inside a Studio Web project — the granular cousin of `uip agent pull` / `push`, which move whole `.uis` archives. Use `file` when you want to read or overwrite a specific file (for example, patch `agent.json` in place) without pulling and repacking the whole solution.

`uip agent file` operates on the individual files inside a Studio Web project — the granular cousin of `uip agent pull` / `push`, which move whole `.uis` archives. Use `file` when you want to read or overwrite a specific file (for example, patch `agent.json` in place) without pulling and repacking the whole solution.

Every subcommand requires 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).

## Synopsis

```
uip agent file list <projectId>                                    [--login-validity <minutes>]
uip agent file get  <projectId> <fileId> [-d <path>]               [--login-validity <minutes>]
uip agent file put  <projectId> <fileId> <localPath>               [--login-validity <minutes>]
```

`<projectId>` is a **Studio Web project** UUID — the inner project inside a solution, not the solution itself. Get one from the `CloudProjectId` field of `uip agent push`, from the `projects[]` array in `uip agent list`, or from `SolutionStorage.json` in a pushed project.

## uip agent file list

List the files inside a Studio Web project as a flat tree.

### Arguments

- `<projectId>` *(required)* — Studio Web project UUID.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

### Example

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

### Data shape (--output json)

```json
{
  "Code": "AgentFileList",
  "Data": [
    {
      "Path": "Agent/agent.json",
      "Id": "a1b2c3d4-0000-0000-0000-000000000201",
      "Name": "agent.json",
      "FileType": "json",
      "IsMain": "true",
      "IsEntryPoint": "true"
    }
  ]
}
```

`Path` is the full slash-separated path from the project root, including the nested folder names. `IsMain` and `IsEntryPoint` are stringified booleans (`"true"` / `"false"`). Empty projects return `Data: { "Message": "No files found in project" }`.

## uip agent file get

Download a single file. Either write it to disk or base64-encode it into the response.

### Arguments

- `<projectId>` *(required)* — Project UUID.
- `<fileId>` *(required)* — File UUID (from `file list`).

### Options

| Flag | Default | Purpose |
|---|---|---|
| `-d, --destination <path>` | — *(write to response)* | Local path to write the file to. Parent directory is created automatically. |
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

### Examples

```bash
# Download to a specific file path
uip agent file get \
  a1b2c3d4-0000-0000-0000-000000000001 \
  a1b2c3d4-0000-0000-0000-000000000201 \
  -d ./agent.json

# Fetch without writing to disk (content is inlined base64)
uip agent file get \
  a1b2c3d4-0000-0000-0000-000000000001 \
  a1b2c3d4-0000-0000-0000-000000000201
```

### Data shape (--output json)

### With `-d`

```json
{
  "Code": "AgentFileGet",
  "Data": {
    "Status": "File downloaded",
    "ProjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "FileId": "a1b2c3d4-0000-0000-0000-000000000201",
    "Output": "/abs/path/agent.json"
  }
}
```

**Without `-d`** (inlined):

```json
{
  "Code": "AgentFileGet",
  "Data": {
    "Status": "File downloaded",
    "ProjectId": "…",
    "FileId": "…",
    "Content": "<base64>",
    "Encoding": "base64"
  }
}
```

## uip agent file put

Upload/overwrite a file in a Studio Web project. The file is sent as multipart form data to `PUT /api/Project/<projectId>/FileOperations/File/<fileId>`.

### Arguments

- `<projectId>` *(required)* — Project UUID.
- `<fileId>` *(required)* — File UUID to overwrite.
- `<localPath>` *(required)* — Local file path to upload.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

### Example

```bash
uip agent file put \
  a1b2c3d4-0000-0000-0000-000000000001 \
  a1b2c3d4-0000-0000-0000-000000000201 \
  ./agent.json
```

### Data shape (--output json)

```json
{
  "Code": "AgentFilePut",
  "Data": {
    "Status": "File uploaded",
    "ProjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "FileId": "a1b2c3d4-0000-0000-0000-000000000201",
    "LocalPath": "/abs/path/agent.json"
  }
}
```

## Related

- [`uip agent pull`](./uip-agent-push-pull.md#uip-agent-pull) — download the entire solution as a `.uis` archive.
- [`uip agent push`](./uip-agent-push-pull.md#uip-agent-push) — import a project (new or overwrite).
- [`uip agent list`](./uip-agent-list-share.md#uip-agent-list) — enumerate solutions (and their projects).

## See also

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