> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# gcai files CLI commands

> Reference for the `gcai files` commands in the GC AI CLI, with the synopsis and flags for each command.

## `gcai files upload`

Upload a file

```bash theme={null}
gcai files upload <file> [--folder-id <value>] [--project-id <value>] [--scope <my-files|organization>]
```

| Flag | Type | Required | Description |
| - | - | - | - |
| `--folder-id <value>` | `string` | | Target folder ID. Defaults to the user's "My Files" folder. Mutually exclusive with `project_id` and `scope`. |
| `--project-id <value>` | `string` | | Upload the file into a project. The file is placed in the project's upload folder and linked to the project. Mutually exclusive with `folder_id` and `scope`. |
| `--scope <my-files\|organization>` | `my-files \| organization` | | Upload to the root of a meta-collection ("my-files" or "organization"). Mutually exclusive with `folder_id` and `project_id`. `shared-with-me` is not valid for upload. |

Wraps `POST /files` — see [Upload a file](/api-reference/upload-file) for full parameter semantics.

## `gcai files search`

Search files

```bash theme={null}
gcai files search <q> [--scope <my-files|shared-with-me|organization>] [--project-id <value>]
```

| Flag | Type | Required | Description |
| - | - | - | - |
| `--scope <my-files\|shared-with-me\|organization>` | `my-files \| shared-with-me \| organization` | | Optional scope filter (user-scoped keys only). When omitted, searches all files the user can read. Mutually exclusive with `project_id`. |
| `--project-id <value>` | `string` | | Optional project filter. Constrains the search to files linked to this project. Mutually exclusive with `scope`. |

Wraps `GET /files` — see [Search files](/api-reference/search-files) for full parameter semantics.

## `gcai files get`

Get file status

```bash theme={null}
gcai files get <id>
```

Wraps `GET /files/{id}` — see [Get file status](/api-reference/get-file-status) for full parameter semantics.

## `gcai files move`

Move a file

```bash theme={null}
gcai files move <id> --folder-id <value>
```

| Flag | Type | Required | Description |
| - | - | - | - |
| `--folder-id <value>` | `string` | yes | Target folder ID to move the file to. Pass null to move to the root. |

Wraps `PATCH /files/{id}` — see [Move a file](/api-reference/update-file) for full parameter semantics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.