> ## Documentation Index
> Fetch the complete documentation index at: https://komga-sdk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Settings

> Manage global and user-specific client settings

Client settings store reader and UI preferences as key-to-setting maps. Global settings provide defaults for every user; user settings override a global value when the same key is present.

Each generated operation returns `{ data, error, request, response }`. Operations with parameters take a flat parameter object first and `{ client }` second.

## Global settings

### List global settings

```typescript theme={null}
import { getGlobalSettings } from 'komga-sdk';

const result = await getGlobalSettings({ client });
for (const [key, setting] of Object.entries(result.data ?? {})) {
  console.log(`${key} = ${setting.value}`);
}
```

Unauthenticated requests receive only settings whose `allowUnauthorized` value is true. An authenticated response is still a map keyed by setting name, not an array.

### Save global settings

> [!WARNING]
>
> Requires the **ADMIN** role.

`saveGlobalSetting` accepts a map. Every global value contains `value` and `allowUnauthorized`; setting the latter to false prevents unauthenticated clients from seeing the key:

```typescript theme={null}
import { saveGlobalSetting } from 'komga-sdk';

await saveGlobalSetting(
  {
    body: {
      'webui.theme.mode': { value: 'dark', allowUnauthorized: false },
      'reader.background': { value: 'BLACK', allowUnauthorized: true },
    },
  },
  { client },
);
```

Setting names are namespaced lower-case keys such as `application.domain.key`. The patch returns no content; inspect `result.error` if the save needs confirmation.

### Delete global settings

> [!WARNING]
>
> Requires the **ADMIN** role.

Pass setting keys as the flat `body` parameter:

```typescript theme={null}
import { deleteGlobalSettings } from 'komga-sdk';

await deleteGlobalSettings(
  { body: ['webui.theme.mode', 'reader.background'] },
  { client },
);
```

Deleting a global key removes the default; it does not remove a user's override of the same key.

## User settings

### List user settings

```typescript theme={null}
import { getUserSettings } from 'komga-sdk';

const result = await getUserSettings({ client });
for (const [key, setting] of Object.entries(result.data ?? {})) {
  console.log(`${key} = ${setting.value}`);
}
```

### Save user settings

User setting values use the same map shape without `allowUnauthorized`:

```typescript theme={null}
import { saveUserSetting } from 'komga-sdk';

await saveUserSetting(
  {
    body: {
      'reader.pageFit': { value: 'WIDTH' },
      'reader.background': { value: 'BLACK' },
    },
  },
  { client },
);
```

### Delete user settings

Deleting a key exposes the global default again when one exists:

```typescript theme={null}
import { deleteUserSettings } from 'komga-sdk';

await deleteUserSettings(
  { body: ['reader.pageFit', 'reader.background'] },
  { client },
);
```

## Workflows

### Apply global defaults with user overrides

Both responses are maps. Copy global entries first, then overwrite them with user entries:

```typescript theme={null}
import { getGlobalSettings, getUserSettings } from 'komga-sdk';

async function getEffectiveSettings() {
  const [global, user] = await Promise.all([
    getGlobalSettings({ client }),
    getUserSettings({ client }),
  ]);

  const effective = new Map<string, string>();
  for (const [key, setting] of Object.entries(global.data ?? {})) {
    effective.set(key, setting.value);
  }
  for (const [key, setting] of Object.entries(user.data ?? {})) {
    effective.set(key, setting.value);
  }
  return effective;
}
```

### Reset user settings to defaults

Read the user map, collect its keys, then send those keys to the delete operation. An empty map needs no request:

```typescript theme={null}
import { deleteUserSettings, getUserSettings } from 'komga-sdk';

async function resetUserSettings() {
  const current = await getUserSettings({ client });
  const keys = Object.keys(current.data ?? {});
  if (keys.length === 0) return;

  await deleteUserSettings({ body: keys }, { client });
}
```

### Update one setting while preserving others

Because save accepts a map, send only the key being changed; other user settings remain untouched:

```typescript theme={null}
import { saveUserSetting } from 'komga-sdk';

async function setPageFit(value: string) {
  return saveUserSetting(
    { body: { 'reader.pageFit': { value } } },
    { client },
  );
}
```

## Handle failures

Generated calls do not throw for an HTTP error by default. A 401 indicates missing authentication; a 403 on global writes indicates that the caller is not an admin:

```typescript theme={null}
import { getGlobalSettings } from 'komga-sdk';

const result = await getGlobalSettings({ client });
if (result.error) {
  console.error('Settings request failed', result.response?.status, result.error);
}
```

Use `unwrap` when your application wants exceptions; it throws `KomgaApiError` for an unsuccessful result. See [Quickstart](/quickstart) for the pattern.

## Next steps

> **[Users](/guides/users)**
>
> Manage users and per-user preferences.

> **[Admin](/guides/admin)**
>
> Configure server-level administrative settings.

> **[Authentication](/authentication)**
>
> Configure the client used by these operations.


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