> ## 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 folders CLI commands

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

## `gcai folders list`

List folders

```bash theme={null}
gcai folders list [--limit <number>] [--offset <number>] [--q <value>] [--scope <my-files|shared-with-me|organization>]
```

| Flag | Type | Required | Description |
| - | - | - | - |
| `--limit <number>` | `number` | | Max items to return (default 100, max 500) |
| `--offset <number>` | `number` | | Number of items to skip (default 0) |
| `--q <value>` | `string` | | Case-insensitive substring search on folder name or description. System-owned collection types (my-files, org-files, etc.) are excluded from results. Composes with `scope`. |
| `--scope <my-files\|shared-with-me\|organization>` | `my-files \| shared-with-me \| organization` | | Filter folders to a single meta-collection. Requires a user-scoped API key. |

Wraps `GET /folders` — see [List folders](/api-reference/list-folders) for full parameter semantics.

## `gcai folders create`

Create a folder

```bash theme={null}
gcai folders create <name> [--description <value>] [--parent-folder-id <value>] [--scope <my-files|organization>]
```

| Flag | Type | Required | Description |
| - | - | - | - |
| `--description <value>` | `string` | | Optional description |
| `--parent-folder-id <value>` | `string` | | Parent folder ID. Mutually exclusive with `scope`. If both are omitted, creates a top-level folder. |
| `--scope <my-files\|organization>` | `my-files \| organization` | | Create the folder at the root of a meta-collection. Mutually exclusive with `parent_folder_id`. `shared-with-me` is not valid for create. |

Wraps `POST /folders` — see [Create a folder](/api-reference/create-folder) for full parameter semantics.

## `gcai folders get`

Get a folder

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

Wraps `GET /folders/{id}` — see [Get a folder](/api-reference/get-folder) for full parameter semantics.

## `gcai folders update`

Update a folder

```bash theme={null}
gcai folders update <id> [--name <value>] [--description <value>] [--parent-folder-id <value>] [--is-access-controlled]
```

| Flag | Type | Required | Description |
| - | - | - | - |
| `--name <value>` | `string` | | New folder name (minimum 2 characters) |
| `--description <value>` | `string` | | New folder description |
| `--parent-folder-id <value>` | `string` | | Target parent folder ID. The destination must not be the folder itself or one of its descendants. |
| `--is-access-controlled` | `boolean` | | Whether the folder requires explicit access grants |

Wraps `PATCH /folders/{id}` — see [Update a folder](/api-reference/update-folder) for full parameter semantics.

## `gcai folders delete`

Delete a folder

```bash theme={null}
gcai folders delete <id> [--recursive <true|false>]
```

| Flag | Type | Required | Description |
| - | - | - | - |
| `--recursive <true\|false>` | `true \| false` | | When `true`, recursively delete subfolders and files. Defaults to `false`. |

Wraps `DELETE /folders/{id}` — see [Delete a folder](/api-reference/delete-folder) for full parameter semantics.

## `gcai folders children`

List a folder's children

```bash theme={null}
gcai folders children <id>
```

Wraps `GET /folders/{id}/children` — see [List a folder's children](/api-reference/list-folder-children) for full parameter semantics.


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