> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# Configure your studios and CLI to use Media Library

Once Media Library is enabled for your organization, you can connect it to your Studio and the CLI.

This article covers enabling Media Library in your studio, managing asset sources, and configuring the `sanity` CLI to create and deploy aspects.

**This is a paid feature**
This feature is available as an addon for certain Enterprise plans. [Talk to sales](https://www.sanity.io/contact/sales?ref=docs) to learn more.

Prerequisites:

- `npm`, `pnpm`, or a similar package manager capable of installing and running the `sanity` CLI.
- Read/write access to your organization's Media Library.
- Studio v3.82.0 or later for Studio integration. [Learn how to upgrade your studios](https://www.sanity.io/docs/studio/upgrade).

## Find your Media Library ID

When you interact with the `sanity media` commands, you're prompted to select your library. If you only have a single organization, you should see a single library. If you're a member of multiple organizations, you can parse your organization and library ID using the URL.

Navigate to [sanity.io/welcome](https://sanity.io/welcome), select your organization, then select the Media Library app. The URL for your library includes the `mediaLibraryId`.

```text
https://www.sanity.io/@YOUR_ORGANIZATION_ID/media/YOUR_MEDIA_LIBRARY_ID/assets
```

Replace `YOUR_ORGANIZATION_ID` and `YOUR_MEDIA_LIBRARY_ID` with the values from your library's URL. The `YOUR_MEDIA_LIBRARY_ID` value is your `mediaLibraryId`.

## Configure Studio

Media Library integration with Studio lets editors select assets from the library for use in their documents, and upload new files and images to the library.

![The Studio image selector interface with Media Library included.](https://cdn.sanity.io/images/3do82whm/next/a4583e5572cb2473fcdac34aadce64df0c56358c-1369x486.png)

Enable Media Library support by setting `mediaLibrary.enabled` to `true` in your `sanity.config.ts` file.

To ensure full functionality, also enable token-based authentication by setting `auth.loginMethod` to `'token'`.

**sanity.config.ts**

```typescript
import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'

export default defineConfig({
  projectId: 'YOUR_PROJECT_ID',
  dataset: 'YOUR_DATASET',
  mediaLibrary: {
    enabled: true,
    // Optional: pin the Studio to a specific library
    libraryId: 'YOUR_MEDIA_LIBRARY_ID',
  },
  auth: {
    loginMethod: 'token',
  },
  plugins: [structureTool()],
  schema: {
    // ...
  },
})
```

The optional `libraryId` setting connects the Studio to a specific library. If you don't provide it, the Media Library is detected automatically. Set it to the `mediaLibraryId` from your library's URL (see "Find your Media Library ID") if your studio does not detect the library.

### Authentication

Some Media Library features are unsupported when using cookie-based authentication. To ensure full functionality, we strongly recommend using token-based authentication.

> [!NOTE]
> When Media Library detects cookie-based authentication, it displays a warning banner.

Currently unsupported features:

- Previewing private assets, both in Studio and when selecting assets from the Media Library
- Managing signing keys
- Downloading assets
- Syncing asset version usage

## Optional: disable the default source

If you want to move completely to Media Library, you can disable the default media source. Use the `form.image.assetSources` configuration in your Studio config file (`sanity.config.ts`) to filter the sources.

This example keeps Media Library and any custom sources, but removes the default media select option.

**sanity.config.ts**

```typescript
import {defineConfig} from 'sanity'

export default defineConfig({
  // ... rest of config

  mediaLibrary: {
    enabled: true,
  },
  form: {
    // Disable the default for image assets
    image: {
      assetSources: (sources) => sources.filter((source) => source.name !== 'sanity-default')
    },
    // Disable the default for file assets
    file: {
      assetSources: (sources) => sources.filter((source) => source.name !== 'sanity-default')
    }
  },

  // ... rest of config
})
```

If you'd like to be more explicit and target the Media Library source, you can do so by comparing the source name with `sanity-media-library`.

## Add filters to the image type selector

You can add selectable filters to the Studio image type by adding the `mediaLibrary` option to the image type's `options` object. Image filters require Studio v4.2.0 or later.

**imageType.ts**

```typescript
import {defineType} from 'sanity'

export default defineType({
  name: 'imageWithMediaLibraryFilters',
  title: 'Image with Media Library filter',
  type: 'image',
  options: {
    mediaLibrary: {
      filters: [
        {
          name: 'Has colorDetails aspect',
          query: 'defined(aspects.colorDetails)',
        },
        {
          name: 'Greater than 4000px wide',
          query: 'currentVersion->metadata.dimensions.width > 4000',
        },
      ],
    },
  },
})
```

Each filter has a `name` and `query`. The query is a GROQ query filter that runs against the Media Library dataset. If it returns true, the matching image is displayed.

## Configure the CLI

Tell the `sanity` CLI where to define your aspects by updating `sanity.cli.ts`.

**sanity.cli.ts**

```typescript
import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: 'YOUR_PROJECT_ID',
    dataset: 'YOUR_DATASET'
  },
  mediaLibrary: {
    // set the path relative to the location of sanity.cli.ts.
    aspectsPath: 'aspects',
  },
})
```

With the aspects path defined, you can now use the `media` commands to [create and deploy aspects](https://www.sanity.io/docs/media-library/create-aspect).



## Related changelog entries

Entries are listed newest first; each link points to the full entry as markdown. Follow one when you need to know what changed, when, or why — for example, to summarize recent updates, explain behavior that differs from older documentation, or check whether a fix has shipped.

- [Sanity Studio v4.2.0: New openapi CLI command, Media Library filters in Studio, and additional fixes](https://www.sanity.io/docs/changelog/7dd374d4-1037-4f42-bad5-7ee7d53ee935.md) — July 29, 2025