---
title: space folders
description: Manage the Space folder tree.
canonical_url: https://orchestor.io/docs/en/space/cli/folders
markdown_url: https://orchestor.io/docs/en/space/cli/folders.md
contentType: reference
---

# space folders

`orc space folders` lists, creates, updates, and archives folders in the Space folder tree. These are the same folders shown in the sidebar folder tree.

Authentication and a selected Workspace are required. Creating, updating, and archiving folders and moving files or folders require `files:write`. Moving documents and sheets requires `doc:update` instead.

## Usage

```bash title="terminal"
orc space folders list --workspace YOUR_WORKSPACE_ID --format json
```

*List the folders in a Workspace.*

## Subcommands

### `list`

Returns every folder that is not archived. With `--project-id`, returns only folders whose nearest explicit project matches. Archived ancestors still supply the project.

```bash title="terminal"
orc space folders list [options]
```

#### Unique options

##### `--project-id`

value

Type: `string`. Optional.

```bash title="terminal"
orc space folders list --project-id <value>
```

### `create`

Creates a folder with a `title`. Set the parent folder with `parent_id`, the project with `project_id`, and the display with `color` and `position`. Omitted values default to no parent, no project, no color, and position 0.

```bash title="terminal"
orc space folders create [options]
```

#### Unique options

##### `--color`

Body field: color; (use "null" or "reset" to clear); max 128 chars

Type: `string`. Optional.

```bash title="terminal"
orc space folders create --color <value>
```

##### `--parent-id`

Body field: parent_id; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc space folders create --parent-id <value>
```

##### `--position`

Body field: position

Type: `number`. Optional.

```bash title="terminal"
orc space folders create --position <value>
```

##### `--project-id`

Body field: project_id; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc space folders create --project-id <value>
```

##### `--title`

(required) Body field: title; max 256 chars

Type: `string`. Optional.

```bash title="terminal"
orc space folders create --title <value>
```

### `update`

Changes a folder's title, color, position, or project. Changing `parent_id` moves the folder under another folder, and `null` moves it to the top level. Parent folders and projects must belong to the same Workspace, and moving a folder into itself or a descendant returns 400.

```bash title="terminal"
orc space folders update <id> [options]
```

#### Unique options

##### `--color`

Body field: color; (use "null" or "reset" to clear); max 128 chars

Type: `string`. Optional.

```bash title="terminal"
orc space folders update <id> --color <value>
```

##### `--parent-id`

Body field: parent_id; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc space folders update <id> --parent-id <value>
```

##### `--position`

Body field: position

Type: `number`. Optional.

```bash title="terminal"
orc space folders update <id> --position <value>
```

##### `--project-id`

Body field: project_id; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc space folders update <id> --project-id <value>
```

##### `--title`

Body field: title; max 256 chars

Type: `string`. Optional.

```bash title="terminal"
orc space folders update <id> --title <value>
```

### `archive`

Archives the folder with the given ID.

```bash title="terminal"
orc space folders archive <id> [options]
```

### `space items folder set`

Moves a document, sheet, file, or folder into a folder. `kind` is `document`, `sheet`, `file`, or `folder`. Passing `null` as `folder_id` removes the item from its folder. Moving a folder runs the same cycle checks as `folders update`.

```bash title="terminal"
orc space items folder set <kind> <id> [options]
```

#### Unique options

##### `--folder-id`

(required) Body field: folder_id; (use "null" or "reset" to clear)

Type: `string`. Optional.

```bash title="terminal"
orc space items folder set <kind> <id> --folder-id <value>
```

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc space folders`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

[Documentation index](https://orchestor.io/docs/llms.txt)