# SmallForce CLI: Media Library commands

Browse and organise the team's Media Library: favourites and folders

This page covers 10 `smallforce library` commands. It is generated from SmallForce CLI 0.1.17; run `smallforce library --help` (or any command with `--help`) to see the same reference for the version you have installed. New to the CLI? Start with [installation and authentication](/docs/cli/overview#install-and-authenticate-the-smallforce-cli) and [JSON output](/docs/cli/overview#use-smallforce-cli-json-output-in-agents-and-scripts).

```text
The Library holds the organization's images, videos and audio: what was generated,
uploaded, or imported from social accounts. Folders are shared collections: an item
can be in several, and removing it from a folder (or deleting the folder) never
deletes the file. Favourites are one list for the whole team.

Folders are named by id or by name (case-insensitive), e.g. "Spring campaign".

All commands support --json for stable machine-readable output.
```

## Common options

Most commands accept these options as well as their own. Every command also accepts `-h, --help`.

| Option | Description |
| --- | --- |
| `--api-key <key>` | SmallForce API key, or set SMALLFORCE_API_KEY |
| `--backend-url <url>` | SmallForce backend URL, or set SMALLFORCE_BACKEND_URL |
| `--json` | Print stable machine-readable JSON |
| `--text` | Print human-readable text |
| `--format <format>` | Output format: text or json |

## `smallforce library list`

List Library items, newest first

**Usage:** `smallforce library list [options]`

| Option | Description |
| --- | --- |
| `--folder <folder>` | Only this folder's items (id or name) |
| `--favorites` | Only the team's favourites |
| `--kind <kind>` | image, video or audio |
| `--source <origin>` | generated, uploaded or imported |
| `--search <text>` | Match the file name or the prompt that made it |
| `--limit <n>` | Items per page, 1 to 100 (default 48) |
| `--cursor <cursor>` | nextCursor from the previous page |

Also accepts the common options listed at the top of this page.

```text
Examples:
  $ smallforce library list
  $ smallforce library list --folder "Spring campaign" --kind image
  $ smallforce library list --favorites --search "bakery" --json
```

## `smallforce library get`

Show one item: its prompt, folders, favourite and a download link

**Usage:** `smallforce library get [options] <assetId>`

| Argument | Description |
| --- | --- |
| `assetId` | Item (asset) id |

| Option | Description |
| --- | --- |
| `--out <path>` | Download the file to this path |

Also accepts the common options listed at the top of this page.

```text
Examples:
  $ smallforce library get <assetId>
  $ smallforce library get <assetId> --out ./hero.png
```

## `smallforce library folders`

List, create, update and delete Library folders

### `smallforce library folders list`

List the folders in sidebar order

**Usage:** `smallforce library folders list [options]`

Also accepts the common options listed at the top of this page.

### `smallforce library folders create`

Create a folder

**Usage:** `smallforce library folders create [options] <name>`

| Argument | Description |
| --- | --- |
| `name` | Folder name, up to 80 characters |

| Option | Description |
| --- | --- |
| `--color <hex>` | Colour as #rrggbb |
| `--icon <key>` | Icon key, e.g. folder, star, megaphone, camera |

Also accepts the common options listed at the top of this page.

```text
Examples:
  $ smallforce library folders create "Spring campaign" --color "#3b74d6" --icon megaphone
```

### `smallforce library folders update`

Rename or restyle a folder

**Usage:** `smallforce library folders update [options] <folder>`

| Argument | Description |
| --- | --- |
| `folder` | Folder id or name |

| Option | Description |
| --- | --- |
| `--name <name>` | New name |
| `--color <hex>` | New colour as #rrggbb |
| `--icon <key>` | New icon key |

Also accepts the common options listed at the top of this page.

```text
Examples:
  $ smallforce library folders update "Spring campaign" --name "Summer campaign"
```

### `smallforce library folders delete`

Delete a folder; its files stay in the Library

**Usage:** `smallforce library folders delete [options] <folder>`

| Argument | Description |
| --- | --- |
| `folder` | Folder id or name |

Also accepts the common options listed at the top of this page.

## `smallforce library add`

Add items to a folder

**Usage:** `smallforce library add [options] <folder> <assetIds...>`

| Argument | Description |
| --- | --- |
| `folder` | Folder id or name |
| `assetIds` | Item (asset) ids, up to 100 |

Also accepts the common options listed at the top of this page.

```text
Examples:
  $ smallforce library add "Spring campaign" <assetId> <assetId>
```

## `smallforce library remove`

Take items out of a folder (the files stay)

**Usage:** `smallforce library remove [options] <folder> <assetIds...>`

| Argument | Description |
| --- | --- |
| `folder` | Folder id or name |
| `assetIds` | Item (asset) ids, up to 100 |

Also accepts the common options listed at the top of this page.

## `smallforce library favorite`

Add items to the team's favourites

**Usage:** `smallforce library favorite [options] <assetIds...>`

| Argument | Description |
| --- | --- |
| `assetIds` | Item (asset) ids, up to 100 |

Also accepts the common options listed at the top of this page.

## `smallforce library unfavorite`

Remove items from the team's favourites

**Usage:** `smallforce library unfavorite [options] <assetIds...>`

| Argument | Description |
| --- | --- |
| `assetIds` | Item (asset) ids, up to 100 |

Also accepts the common options listed at the top of this page.
