Skip to main content
Client settings store preferences for web and mobile readers. Settings can be global (admin-managed) or user-specific.
Global settings affect all users. User settings override global defaults when present.

​
Global settings

​
List global settings

import { getGlobalSettings } from 'komga-sdk';

const result = await getGlobalSettings({ client });

if (result.data) {
  result.data.forEach(setting => {
    console.log(`${setting.key} = ${setting.value}`);
  });
}

​
Save a global setting

Requires ADMIN role.
import { saveGlobalSetting } from 'komga-sdk';

await saveGlobalSetting({
  client,
  body: {
    key: 'webui.theme.mode',
    value: 'dark',
  },
});

​
Delete global settings

Requires ADMIN role.
import { deleteGlobalSettings } from 'komga-sdk';

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

​
User settings

​
List user settings

import { getUserSettings } from 'komga-sdk';

const result = await getUserSettings({ client });

if (result.data) {
  result.data.forEach(setting => {
    console.log(`${setting.key} = ${setting.value}`);
  });
}

​
Save a user setting

import { saveUserSetting } from 'komga-sdk';

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

​
Delete user settings

import { deleteUserSettings } from 'komga-sdk';

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

​
Common workflows

​
Apply global defaults with user overrides

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 setting of global.data ?? []) {
    effective.set(setting.key, setting.value);
  }

  for (const setting of user.data ?? []) {
    effective.set(setting.key, setting.value);
  }

  return effective;
}

​
Reset user settings to defaults

import { getUserSettings, deleteUserSettings } from 'komga-sdk';

async function resetUserSettings() {
  const result = await getUserSettings({ client });
  if (!result.data) return;

  await deleteUserSettings({
    client,
    body: {
      keys: result.data.map(s => s.key),
    },
  });
}

​
Error handling

import { getGlobalSettings } from 'komga-sdk';

const result = await getGlobalSettings({ client });

if (result.error) {
  switch (result.response?.status) {
    case 401:
      console.error('Not authenticated');
      break;
    case 403:
      console.error('Admin access required');
      break;
    default:
      console.error('Error fetching settings:', result.error);
  }
}

​
Next steps

Users

Manage users and per-user preferences.

Admin

Server settings and administration.