refactor(cli): rewrite CLI for reliability and better UX

Replace brocli framework with Node's built-in util.parseArgs and a declarative command registry. The CLI no longer hangs after completing because: - DB connections are lazily created and explicitly closed - Winston/Redis logging is excluded from the bundle entirely - process.exit() is always called with proper exit codes Additional improvements: - Bundle size reduced from 5.3MB to 1.2MB (native drivers externalized) - Proper column-aligned table output for list commands - --json flag on list commands for scripting/automation - Per-command --help with usage examples - Execution timing shown on success - Consistent exit codes (0=success, 1=error, 2=usage) - Docker wrapper sets DISABLE_REDIS_LOGS and uses exec
chore(release): 1.61.1 [skip ci]
2026-05-21 16:05:27 +02:00 · 2026-05-18 19:45:44 +00:00 · 2026-05-18 21:44:47 +02:00 · 2026-05-08 20:06:52 +00:00 · 2026-05-08 20:05:49 +00:00 · 2026-05-08 19:26:12 +00:00
47 changed files with 2915 additions and 1688 deletions
@@ -45,6 +45,12 @@ DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'

 TURBO_TELEMETRY_DISABLED=1

+# Comma-separated paths to Docker-compatible Unix sockets.
+# Useful for connecting to multiple runtimes (Docker + Podman) simultaneously.
+# When unset and no TCP hosts configured, defaults to /var/run/docker.sock.
+# Example: DOCKER_SOCKET_PATHS=/var/run/docker.sock,/run/user/1000/podman/podman.sock
+# DOCKER_SOCKET_PATHS=
+
 # Enable kubernetes tool
 # ENABLE_KUBERNETES=true

@@ -22,7 +22,7 @@
      automerge: true,
    },
    {
-      // disallow automerge for dependencies requiring postinstall scripts
+      // disallow automerge for onlyBuiltDependencies
      matchPackageNames: [
        "@tree-sitter-grammars/tree-sitter-yaml",
        "bcrypt",
@@ -39,7 +39,7 @@
  ],
  // Updates lockfile for prebuilt-debian after if package.json is updated, otherwise only root lockfile is updated
  postUpgradeTasks: {
-    commands: ["cd deployments/prebuilt-debian && pnpm install --lockfile-only"],
+    commands: ["cd deployments/prebuilt-debian && pnpm install --ignore-workspace --lockfile-only"],
    fileFilters: ["deployments/prebuilt-debian/pnpm-lock.yaml"],
    executionMode: "update",
  },
@@ -0,0 +1,6 @@
+# Expo doesn't play nice with pnpm by default. 
+# The symbolic links of pnpm break the rules of Expo monorepos.
+# @link https://docs.expo.dev/guides/monorepos/#common-issues
+node-linker=hoisted
+strict-peer-dependencies=false
+engine-strict=true
@@ -1,3 +1,34 @@
+## [1.61.1](https://github.com/homarr-labs/homarr/compare/v1.61.0...v1.61.1) (2026-05-18)
+
+### Bug Fixes
+
+* **downloads-widget:** increase name column default width ratio ([e9142c0](https://github.com/homarr-labs/homarr/commit/e9142c0dbcaca6cd9215b5292a2d139d96919b51))
+
+## [1.61.0](https://github.com/homarr-labs/homarr/compare/v1.60.0...v1.61.0) (2026-05-08)
+
+### Features
+
+* add auto/system appearance mode + fix dark mode system resources charts ([#5492](https://github.com/homarr-labs/homarr/issues/5492)) ([831b622](https://github.com/homarr-labs/homarr/commit/831b6221fdf21fe4913b0f165ef551afeada4f33))
+* add pwa support ([#5530](https://github.com/homarr-labs/homarr/issues/5530)) ([277a509](https://github.com/homarr-labs/homarr/commit/277a509f490d57bb6547c86c417c29c0e7af7e40))
+* add Umami Analytics integration and widget ([#5362](https://github.com/homarr-labs/homarr/issues/5362)) ([43cc68b](https://github.com/homarr-labs/homarr/commit/43cc68bdd49c4877012e39e23355f6506aea7f4e))
+* **docker:** Podman compatibility, multi-socket support, per-host error isolation ([#5425](https://github.com/homarr-labs/homarr/issues/5425)) ([56af6bc](https://github.com/homarr-labs/homarr/commit/56af6bcaf00e980e4c7a40d8e912901cd1395f5a))
+* **entity-state:** add data attributes for custom-css styling ([#5655](https://github.com/homarr-labs/homarr/issues/5655)) ([0937555](https://github.com/homarr-labs/homarr/commit/0937555d49c29455bc33307ae5e50bf5b812c7c7))
+* **installations:** support secrets file for all environment variables ([#5125](https://github.com/homarr-labs/homarr/issues/5125)) ([4d30a2e](https://github.com/homarr-labs/homarr/commit/4d30a2e8c48f818bb4947a651b0fec5f64cbf569))
+* **qbittorrent:** add api-key support ([#5677](https://github.com/homarr-labs/homarr/issues/5677)) ([756e8d1](https://github.com/homarr-labs/homarr/commit/756e8d172455f91e40cd8fb5faff6953cc9778c5))
+* **spotlight:** rework !bang search UX ([#4813](https://github.com/homarr-labs/homarr/issues/4813)) ([b5c316b](https://github.com/homarr-labs/homarr/commit/b5c316b825bdffa267fd173a3c39a12269142665))
+
+### Bug Fixes
+
+* **apps:** creation on the fly broken ([#5605](https://github.com/homarr-labs/homarr/issues/5605)) ([3183914](https://github.com/homarr-labs/homarr/commit/3183914a1502555681b73975062ed6ca8a48cb75))
+* **calendar:** keep working integrations when one fails ([#5629](https://github.com/homarr-labs/homarr/issues/5629)) ([44bd16d](https://github.com/homarr-labs/homarr/commit/44bd16d6770d289054df6c7c93adff42d2243252))
+* **lang:** portuguese is linked to brazilian portuguese on crowdin ([#5622](https://github.com/homarr-labs/homarr/issues/5622)) ([62be81e](https://github.com/homarr-labs/homarr/commit/62be81ea607a609a816157686700c54540e1568b))
+* **qbittorrent:** support version 5.2 ([#5672](https://github.com/homarr-labs/homarr/issues/5672)) ([00a0552](https://github.com/homarr-labs/homarr/commit/00a055283e8848542b67d88a656a99fdd0bcb444))
+* **update-checker:** hide prereleases on non-prerelease versions ([#5645](https://github.com/homarr-labs/homarr/issues/5645)) ([b07a4a0](https://github.com/homarr-labs/homarr/commit/b07a4a0f3e3af384ec477bf5c505a705b003de47))
+
+### Reverts
+
+* **deps:** downgrade pnpm to v10 ([#5673](https://github.com/homarr-labs/homarr/issues/5673)) ([44a2973](https://github.com/homarr-labs/homarr/commit/44a2973b1aba1e2c6bd818be022205f3cdb7c943))
+
 ## [1.60.0](https://github.com/homarr-labs/homarr/compare/v1.59.3...v1.60.0) (2026-05-01)

 ### Features
@@ -3,7 +3,11 @@

 # Exempt Renovate‑managed files (no owners)
 package.json
+**/package.json
 package-lock.json
+**/package-lock.json
 pnpm-lock.yaml
+**/pnpm-lock.yaml
+pnpm-workspace.yaml
 Dockerfile
 docker-compose.yml
@@ -30,7 +30,7 @@ VOLUME /appdata

 # Enable homarr cli
 COPY --from=builder /app/packages/cli/cli.cjs /app/apps/cli/cli.cjs
-RUN echo $'#!/bin/bash\ncd /app/apps/cli && node ./cli.cjs "$@"' > /usr/bin/homarr
+RUN echo $'#!/bin/bash\nexport DISABLE_REDIS_LOGS=true\ncd /app/apps/cli && exec node ./cli.cjs "$@"' > /usr/bin/homarr
 RUN chmod +x /usr/bin/homarr

 # Don't run production as root
@@ -58,6 +58,18 @@ const createColumns = (
      return <ContainerStateBadge state={cell.row.original.state} />;
    },
  },
+  {
+    accessorKey: "host",
+    header: t("docker.field.host.label"),
+    size: 140,
+    Cell({ row }) {
+      return (
+        <Text truncate="end" title={row.original.host}>
+          {row.original.host}
+        </Text>
+      );
+    },
+  },
  {
    accessorKey: "image",
    header: t("docker.field.containerImage.label"),
@@ -2,6 +2,5 @@ FROM node:24.15.0-trixie AS base
 WORKDIR /app
 COPY package.json .
 COPY pnpm-lock.yaml .
-COPY pnpm-workspace.yaml .
 RUN corepack enable pnpm && pnpm install --frozen-lockfile
 CMD ["sleep", "60s"]
@@ -4,9 +4,14 @@
  "dependencies": {
    "better-sqlite3": "^12.9.0"
  },
-  "packageManager": "pnpm@11.0.4",
+  "packageManager": "pnpm@10.33.2",
  "engines": {
    "node": ">=24.15.0",
-    "pnpm": ">=11.0.4"
+    "pnpm": ">=10.33.2"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
  }
 }
@@ -1,2 +0,0 @@
-allowBuilds:
-  better-sqlite3: true
@@ -1,6 +1,6 @@
 {
  "name": "homarr",
-  "version": "1.60.0",
+  "version": "1.61.1",
  "private": true,
  "scripts": {
    "build": "cross-env CI=true turbo build",
@@ -57,12 +57,55 @@
    "turbo": "catalog:",
    "typescript": "catalog:",
    "vite-tsconfig-paths": "catalog:",
-    "vitest": "catalog:",
-    "yaml": "catalog:"
+    "vitest": "catalog:"
  },
-  "packageManager": "pnpm@11.0.4",
+  "packageManager": "pnpm@10.33.2",
  "engines": {
    "node": ">=24.15.0",
-    "pnpm": ">=11.0.4"
+    "pnpm": ">=10.33.2"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@tree-sitter-grammars/tree-sitter-yaml",
+      "bcrypt",
+      "better-sqlite3",
+      "cpu-features",
+      "esbuild",
+      "sharp",
+      "ssh2",
+      "tree-sitter",
+      "tree-sitter-json"
+    ],
+    "overrides": {
+      "@babel/helpers@<7.26.10": ">=7.29.2",
+      "@babel/runtime@<7.26.10": ">=7.29.2",
+      "axios@>=1.0.0 <1.8.2": ">=1.16.0",
+      "brace-expansion@>=2.0.0 <=2.0.1": ">=5.0.5",
+      "brace-expansion@>=1.0.0 <=1.1.11": ">=5.0.5",
+      "esbuild@<=0.24.2": ">=0.28.0",
+      "form-data@>=4.0.0 <4.0.4": ">=4.0.5",
+      "hono@<4.6.5": ">=4.12.16",
+      "linkifyjs@<4.3.2": ">=4.3.2",
+      "nanoid@>=4.0.0 <5.0.9": ">=5.1.11",
+      "prismjs@<1.30.0": ">=1.30.0",
+      "proxmox-api>undici": "7.24.6",
+      "react-is": "^19.2.5",
+      "rollup@>=4.0.0 <4.22.4": ">=4.60.2",
+      "sha.js@<=2.4.11": ">=2.4.12",
+      "tar-fs@>=3.0.0 <3.0.9": ">=3.1.2",
+      "tar-fs@>=2.0.0 <2.1.3": ">=3.1.2",
+      "tmp@<=0.2.3": ">=0.2.5",
+      "vite@>=5.0.0 <=5.4.18": ">=8.0.10"
+    },
+    "patchedDependencies": {
+      "@types/node-unifi": "patches/@types__node-unifi.patch",
+      "trpc-to-openapi": "patches/trpc-to-openapi.patch"
+    },
+    "allowUnusedPatches": true,
+    "ignoredBuiltDependencies": [
+      "@scarf/scarf",
+      "core-js-pure",
+      "protobufjs"
+    ]
  }
 }
@@ -138,6 +138,7 @@ const getContainerOrThrowAsync = async (id: string) => {
 interface DockerContainer {
  name: string;
  id: string;
+  host: string;
  state: ContainerState;
  image: string;
  ports: Port[] | undefined;
@@ -15,7 +15,7 @@
    }
  },
  "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --outfile=cli.cjs --external:bcrypt --external:cpu-features --loader:.html=text --loader:.node=text",
+    "build": "esbuild src/index.ts --bundle --platform=node --outfile=cli.cjs --external:bcrypt --external:cpu-features --external:better-sqlite3 --external:mysql2 --external:pg --loader:.html=text --loader:.node=text",
    "clean": "rm -rf .turbo node_modules",
    "format": "prettier --check . --ignore-path ../../.gitignore",
    "lint": "eslint",
@@ -25,12 +25,16 @@
  },
  "prettier": "@homarr/prettier-config",
  "dependencies": {
-    "@drizzle-team/brocli": "catalog:",
    "@homarr/auth": "workspace:^0.1.0",
    "@homarr/common": "workspace:^0.1.0",
+    "@homarr/core": "workspace:^0.1.0",
    "@homarr/db": "workspace:^0.1.0",
    "@homarr/validation": "workspace:^0.1.0",
-    "dotenv": "catalog:"
+    "better-sqlite3": "catalog:",
+    "dotenv": "catalog:",
+    "drizzle-orm": "catalog:",
+    "mysql2": "catalog:",
+    "pg": "catalog:"
  },
  "devDependencies": {
    "@homarr/eslint-config": "workspace:^0.2.0",
@@ -0,0 +1,127 @@
+import Database from "better-sqlite3";
+import { drizzle as drizzleSqlite } from "drizzle-orm/better-sqlite3";
+import { drizzle as drizzleMysql } from "drizzle-orm/mysql2";
+import { drizzle as drizzlePostgres } from "drizzle-orm/node-postgres";
+import mysql from "mysql2";
+import type { Pool as MysqlPool } from "mysql2";
+import { Pool as PostgresPool } from "pg";
+
+import { DB_CASING } from "@homarr/core/infrastructure/db/constants";
+import { dbEnv } from "@homarr/core/infrastructure/db/env";
+import { schema } from "@homarr/db/schema";
+
+const CONNECT_TIMEOUT_MS = 10_000;
+
+const dbConfig = {
+  schema,
+  casing: DB_CASING,
+};
+
+export type CliDatabase = ReturnType<typeof drizzleSqlite<typeof schema>>;
+
+type CliConnection =
+  | { driver: "better-sqlite3"; raw: Database.Database; db: CliDatabase }
+  | { driver: "mysql2"; raw: MysqlPool; db: CliDatabase }
+  | { driver: "node-postgres"; raw: PostgresPool; db: CliDatabase };
+
+let connection: CliConnection | null = null;
+
+const createMysqlPool = () => {
+  const poolOptions = {
+    maxIdle: 0,
+    idleTimeout: 60000,
+    enableKeepAlive: true,
+    connectTimeout: CONNECT_TIMEOUT_MS,
+  };
+
+  if (!dbEnv.HOST) {
+    return mysql.createPool({ ...poolOptions, uri: dbEnv.URL });
+  }
+
+  return mysql.createPool({
+    ...poolOptions,
+    host: dbEnv.HOST,
+    port: dbEnv.PORT,
+    database: dbEnv.NAME,
+    user: dbEnv.USER,
+    password: dbEnv.PASSWORD,
+  });
+};
+
+const createPostgresPool = () => {
+  const poolOptions = {
+    max: 1,
+    idleTimeoutMillis: 60000,
+    connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
+    allowExitOnIdle: true,
+  };
+
+  if (!dbEnv.HOST) {
+    return new PostgresPool({
+      ...poolOptions,
+      connectionString: dbEnv.URL,
+    });
+  }
+
+  return new PostgresPool({
+    ...poolOptions,
+    host: dbEnv.HOST,
+    port: dbEnv.PORT,
+    database: dbEnv.NAME,
+    user: dbEnv.USER,
+    password: dbEnv.PASSWORD,
+  });
+};
+
+const connectionFactories = {
+  "better-sqlite3": (): CliConnection => {
+    const raw = new Database(dbEnv.URL);
+    const db = drizzleSqlite(raw, dbConfig);
+    return { driver: "better-sqlite3", raw, db };
+  },
+  mysql2: (): CliConnection => {
+    const raw = createMysqlPool();
+    const db = drizzleMysql(raw, { ...dbConfig, mode: "default" }) as unknown as CliDatabase;
+    return { driver: "mysql2", raw, db };
+  },
+  "node-postgres": (): CliConnection => {
+    const raw = createPostgresPool();
+    const db = drizzlePostgres({ ...dbConfig, client: raw }) as unknown as CliDatabase;
+    return { driver: "node-postgres", raw, db };
+  },
+};
+
+const closeHandlers: Record<CliConnection["driver"], (entry: CliConnection) => Promise<void>> = {
+  "better-sqlite3": async (entry) => {
+    (entry as Extract<CliConnection, { driver: "better-sqlite3" }>).raw.close();
+  },
+  mysql2: (entry) => {
+    const pool = (entry as Extract<CliConnection, { driver: "mysql2" }>).raw;
+    return new Promise<void>((resolve, reject) => {
+      pool.end((err) => (err ? reject(err) : resolve()));
+    });
+  },
+  "node-postgres": async (entry) => {
+    await (entry as Extract<CliConnection, { driver: "node-postgres" }>).raw.end();
+  },
+};
+
+export const getCliDb = (): CliDatabase => {
+  if (connection) {
+    return connection.db;
+  }
+
+  const driver = dbEnv.DRIVER ?? "better-sqlite3";
+  connection = connectionFactories[driver]();
+  return connection.db;
+};
+
+export const closeCliDbAsync = async (): Promise<void> => {
+  if (!connection) {
+    return;
+  }
+
+  const current = connection;
+  connection = null;
+  await closeHandlers[current.driver](current);
+};
@@ -1,36 +1,35 @@
-import { command } from "@drizzle-team/brocli";
+import { eq } from "drizzle-orm";

-import { db, eq } from "@homarr/db";
+import { getCliDb } from "../cli-db";
+import { requireCredentialsProvider } from "../errors";
 import { users } from "@homarr/db/schema";

-export const fixUsernames = command({
-  name: "fix-usernames",
-  desc: "Changes all credentials usernames to lowercase",
-  // eslint-disable-next-line no-restricted-syntax
-  handler: async () => {
-    if (!process.env.AUTH_PROVIDERS?.toLowerCase().includes("credentials")) {
-      console.error("Credentials provider is not enabled");
-      return;
+export async function fixUsernamesHandler(): Promise<number> {
+  requireCredentialsProvider();
+
+  const db = getCliDb();
+  const credentialUsers = await db.query.users.findMany({
+    where: eq(users.provider, "credentials"),
+  });
+
+  for (const user of credentialUsers) {
+    if (!user.name) {
+      continue;
+    }
+    if (user.name === user.name.toLowerCase()) {
+      continue;
    }

-    const credentialUsers = await db.query.users.findMany({
-      where: eq(users.provider, "credentials"),
-    });
+    await db
+      .update(users)
+      .set({
+        name: user.name.toLowerCase(),
+      })
+      .where(eq(users.id, user.id));

-    for (const user of credentialUsers) {
-      if (!user.name) continue;
-      if (user.name === user.name.toLowerCase()) continue;
+    console.log(`Changed username from ${user.name} to ${user.name.toLowerCase()}`);
+  }

-      await db
-        .update(users)
-        .set({
-          name: user.name.toLowerCase(),
-        })
-        .where(eq(users.id, user.id));
-
-      console.log(`Changed username from ${user.name} to ${user.name.toLowerCase()}`);
-    }
-
-    console.log("All usernames have been fixed");
-  },
-});
+  console.log("All usernames have been fixed");
+  return 0;
+}
@@ -1,39 +1,50 @@
-import { command, string } from "@drizzle-team/brocli";
+import { parseArgs } from "node:util";

-import { db, eq } from "@homarr/db";
+import { eq } from "drizzle-orm";
+
+import type { CliDatabase } from "../cli-db";
+import { getCliDb } from "../cli-db";
+import { CliError } from "../errors";
 import { integrations } from "@homarr/db/schema";

-export const integrationsDelete = command({
-  name: "delete",
-  desc: "Delete an integration by id or name",
-  options: {
-    id: string("id").alias("i").desc("ID of the integration"),
-    name: string("name").alias("n").desc("Name of the integration"),
-  },
-  // eslint-disable-next-line no-restricted-syntax
-  handler: async (options) => {
-    if (!options.id && !options.name) {
-      console.error("Either --id or --name must be provided");
-      return;
-    }
+const integrationLookup: Record<
+  "id" | "name",
+  (db: CliDatabase, value: string) => Promise<{ id: string; name: string } | undefined>
+> = {
+  id: (db, value) =>
+    db.query.integrations.findFirst({
+      where: eq(integrations.id, value),
+    }),
+  name: (db, value) =>
+    db.query.integrations.findFirst({
+      where: eq(integrations.name, value),
+    }),
+};

-    let entry;
-    if (options.id) {
-      entry = await db.query.integrations.findFirst({
-        where: eq(integrations.id, options.id),
-      });
-    } else if (options.name) {
-      entry = await db.query.integrations.findFirst({
-        where: eq(integrations.name, options.name),
-      });
-    }
+export async function integrationsDeleteHandler(args: string[]): Promise<number> {
+  const { values } = parseArgs({
+    args,
+    options: {
+      id: { type: "string", short: "i" },
+      name: { type: "string", short: "n" },
+    },
+  });

-    if (!entry) {
-      console.error("Integration not found");
-      return;
-    }
+  const lookupKey = values.id ? "id" : values.name ? "name" : null;
+  const lookupValue = values.id ?? values.name;

-    await db.delete(integrations).where(eq(integrations.id, entry.id));
-    console.log(`Integration ${entry.name} (${entry.id}) deleted`);
-  },
-});
+  if (!lookupKey || !lookupValue) {
+    throw new CliError("Either --id or --name must be provided", 2);
+  }
+
+  const db = getCliDb();
+  const entry = await integrationLookup[lookupKey](db, lookupValue);
+
+  if (!entry) {
+    throw new CliError("Integration not found");
+  }
+
+  await db.delete(integrations).where(eq(integrations.id, entry.id));
+  console.log(`Integration ${entry.name} (${entry.id}) deleted`);
+  return 0;
+}
@@ -1,21 +1,35 @@
-import { command } from "@drizzle-team/brocli";
+import { parseArgs } from "node:util";

-import { db } from "@homarr/db";
+import { getCliDb } from "../cli-db";
+import { printTable } from "../utils";

-export const integrationsList = command({
-  name: "list",
-  desc: "List all integrations (id and name)",
-  // eslint-disable-next-line no-restricted-syntax
-  handler: async () => {
-    const all = await db.query.integrations.findMany();
-    if (all.length === 0) {
-      console.log("No integrations found");
-      return;
-    }
+export async function integrationsListHandler(args: string[] = []): Promise<number> {
+  const { values } = parseArgs({
+    args,
+    options: {
+      json: { type: "boolean", default: false },
+    },
+    strict: false,
+  });

-    console.log("ID\t\t\t\tName");
-    for (const i of all) {
-      console.log(`${i.id}\t${i.name}`);
-    }
-  },
-});
+  const db = getCliDb();
+  const all = await db.query.integrations.findMany();
+
+  if (values.json) {
+    const output = all.map((i) => ({ id: i.id, name: i.name, kind: i.kind, url: i.url }));
+    console.log(JSON.stringify(output, null, 2));
+    return 0;
+  }
+
+  if (all.length === 0) {
+    console.log("No integrations found");
+    return 0;
+  }
+
+  printTable(
+    ["ID", "Name", "Kind", "URL"],
+    all.map((i) => [i.id, i.name, i.kind, i.url]),
+  );
+  console.log(`\n${all.length} integration(s) total`);
+  return 0;
+}
@@ -1,10 +0,0 @@
-import { command } from "@drizzle-team/brocli";
-
-import { integrationsDelete } from "./integrations-delete";
-import { integrationsList } from "./integrations-list";
-
-export const integrationsRoot = command({
-  name: "integrations",
-  desc: "Group of commands to manage integrations",
-  subcommands: [integrationsList, integrationsDelete],
-});
@@ -1,94 +1,98 @@
-import { command, string } from "@drizzle-team/brocli";
+import { parseArgs } from "node:util";

-import { hashPasswordAsync } from "@homarr/auth";
+import { hashPasswordAsync } from "@homarr/auth/security";
 import { createId } from "@homarr/common";
-import { generateSecureRandomToken } from "@homarr/common/server";
-import { and, count, db, eq } from "@homarr/db";
-import { getMaxGroupPositionAsync } from "@homarr/db/queries";
+import { generateSecureRandomToken } from "../utils";
+import { and, count, eq, max } from "drizzle-orm";
+
+import { getCliDb } from "../cli-db";
+import { CliError, requireCredentialsProvider } from "../errors";
 import { groupMembers, groupPermissions, groups, users } from "@homarr/db/schema";
 import { usernameSchema } from "@homarr/validation/user";

-export const recreateAdmin = command({
-  name: "recreate-admin",
-  desc: "Recreate credentials admin user if none exists anymore",
-  options: {
-    username: string("username").required().alias("u").desc("Name of the admin"),
-  },
-  // eslint-disable-next-line no-restricted-syntax
-  handler: async (options) => {
-    if (!process.env.AUTH_PROVIDERS?.toLowerCase().includes("credentials")) {
-      console.error("Credentials provider is not enabled");
-      return;
-    }
+export async function recreateAdminHandler(args: string[]): Promise<number> {
+  requireCredentialsProvider();

-    const result = await usernameSchema.safeParseAsync(options.username);
+  const { values } = parseArgs({
+    args,
+    options: {
+      username: { type: "string", short: "u" },
+    },
+  });

-    if (!result.success) {
-      console.error("Invalid username:");
-      console.error(result.error.issues.map((error) => `- ${error.message}`).join("\n"));
-      return;
-    }
+  if (!values.username) {
+    throw new CliError("Missing required option: --username / -u", 2);
+  }

-    const totalCount = await db
-      .select({
-        count: count(),
-      })
-      .from(groupPermissions)
-      .leftJoin(groupMembers, eq(groupMembers.groupId, groupPermissions.groupId))
-      .leftJoin(users, eq(users.id, groupMembers.userId))
-      .where(and(eq(groupPermissions.permission, "admin"), eq(users.provider, "credentials")))
-      .then((rows) => rows.at(0)?.count ?? 0);
+  const result = await usernameSchema.safeParseAsync(values.username);
+  if (!result.success) {
+    const messages = result.error.issues.map((issue) => `- ${issue.message}`).join("\n");
+    throw new CliError(`Invalid username:\n${messages}`, 2);
+  }

-    if (totalCount > 0) {
-      console.error("Credentials admin user exists");
-      return;
-    }
+  const db = getCliDb();

-    const existingUser = await db.query.users.findFirst({
-      where: eq(users.name, result.data),
-    });
+  const totalCount = await db
+    .select({
+      count: count(),
+    })
+    .from(groupPermissions)
+    .leftJoin(groupMembers, eq(groupMembers.groupId, groupPermissions.groupId))
+    .leftJoin(users, eq(users.id, groupMembers.userId))
+    .where(and(eq(groupPermissions.permission, "admin"), eq(users.provider, "credentials")))
+    .then((rows: { count: number }[]) => rows.at(0)?.count ?? 0);

-    if (existingUser) {
-      console.error("User with this name already exists");
-      return;
-    }
+  if (totalCount > 0) {
+    throw new CliError("Credentials admin user exists");
+  }

-    const temporaryGroupId = createId();
+  const existingUser = await db.query.users.findFirst({
+    where: eq(users.name, result.data),
+  });

-    const maxPosition = await getMaxGroupPositionAsync(db);
-    await db.insert(groups).values({
-      id: temporaryGroupId,
-      name: temporaryGroupId,
-      position: maxPosition + 1,
-    });
+  if (existingUser) {
+    throw new CliError("User with this name already exists");
+  }

-    await db.insert(groupPermissions).values({
-      groupId: temporaryGroupId,
-      permission: "admin",
-    });
+  const temporaryGroupId = createId();
+  const maxPosition = await db
+    .select({ value: max(groups.position) })
+    .from(groups)
+    .then((result: { value: number | null }[]) => result[0]?.value ?? 1);

-    const password = generateSecureRandomToken(24);
-    const hashedPassword = await hashPasswordAsync(password);
+  await db.insert(groups).values({
+    id: temporaryGroupId,
+    name: temporaryGroupId,
+    position: maxPosition + 1,
+  });

-    const userId = createId();
-    await db.insert(users).values({
-      id: userId,
-      name: result.data,
-      provider: "credentials",
-      password: hashedPassword,
-    });
+  await db.insert(groupPermissions).values({
+    groupId: temporaryGroupId,
+    permission: "admin",
+  });

-    await db.insert(groupMembers).values({
-      groupId: temporaryGroupId,
-      userId,
-    });
+  const password = generateSecureRandomToken(24);
+  const hashedPassword = await hashPasswordAsync(password);
+  const userId = createId();

-    console.log(
-      "We created a new admin user for you. Please keep in mind, that the admin group of it has a temporary name. You should change it to something more meaningful.",
-    );
-    console.log(`\tUsername: ${result.data}`);
-    console.log(`\tPassword: ${password}`);
-    console.log(`\tGroup: ${temporaryGroupId}`);
-    console.log(""); // Empty line for better readability
-  },
-});
+  await db.insert(users).values({
+    id: userId,
+    name: result.data,
+    provider: "credentials",
+    password: hashedPassword,
+  });
+
+  await db.insert(groupMembers).values({
+    groupId: temporaryGroupId,
+    userId,
+  });
+
+  console.log(
+    "We created a new admin user for you. Please keep in mind, that the admin group of it has a temporary name. You should change it to something more meaningful.",
+  );
+  console.log(`\tUsername: ${result.data}`);
+  console.log(`\tPassword: ${password}`);
+  console.log(`\tGroup: ${temporaryGroupId}`);
+  console.log("");
+  return 0;
+}
@@ -1,46 +1,48 @@
-import { command, string } from "@drizzle-team/brocli";
+import { parseArgs } from "node:util";

-import { hashPasswordAsync } from "@homarr/auth";
-import { generateSecureRandomToken } from "@homarr/common/server";
-import { and, db, eq } from "@homarr/db";
+import { hashPasswordAsync } from "@homarr/auth/security";
+import { generateSecureRandomToken } from "../utils";
+import { and, eq } from "drizzle-orm";
+
+import { getCliDb } from "../cli-db";
+import { CliError, requireCredentialsProvider } from "../errors";
 import { sessions, users } from "@homarr/db/schema";

-export const resetPassword = command({
-  name: "reset-password",
-  desc: "Reset password for a user",
-  options: {
-    username: string("username").required().alias("u").desc("Name of the user"),
-  },
-  // eslint-disable-next-line no-restricted-syntax
-  handler: async (options) => {
-    if (!process.env.AUTH_PROVIDERS?.toLowerCase().includes("credentials")) {
-      console.error("Credentials provider is not enabled");
-      return;
-    }
+export async function resetPasswordHandler(args: string[]): Promise<number> {
+  requireCredentialsProvider();

-    const user = await db.query.users.findFirst({
-      where: and(eq(users.name, options.username), eq(users.provider, "credentials")),
-    });
+  const { values } = parseArgs({
+    args,
+    options: {
+      username: { type: "string", short: "u" },
+    },
+  });

-    if (!user?.password) {
-      console.error(`User ${options.username} not found`);
-      return;
-    }
+  if (!values.username) {
+    throw new CliError("Missing required option: --username / -u", 2);
+  }

-    // Generates a new password with 48 characters
-    const newPassword = generateSecureRandomToken(24);
+  const db = getCliDb();
+  const user = await db.query.users.findFirst({
+    where: and(eq(users.name, values.username), eq(users.provider, "credentials")),
+  });

-    await db
-      .update(users)
-      .set({
-        password: await hashPasswordAsync(newPassword),
-      })
-      .where(eq(users.id, user.id));
+  if (!user?.password) {
+    throw new CliError(`User ${values.username} not found`);
+  }

-    await db.delete(sessions).where(eq(sessions.userId, user.id));
-    console.log(`All sessions for user ${options.username} have been deleted`);
+  const newPassword = generateSecureRandomToken(24);

-    console.log("You can now login with the new password");
-    console.log(`New password for user ${options.username}: ${newPassword}`);
-  },
-});
+  await db
+    .update(users)
+    .set({
+      password: await hashPasswordAsync(newPassword),
+    })
+    .where(eq(users.id, user.id));
+
+  await db.delete(sessions).where(eq(sessions.userId, user.id));
+  console.log(`All sessions for user ${values.username} have been deleted`);
+  console.log("You can now login with the new password");
+  console.log(`New password for user ${values.username}: ${newPassword}`);
+  return 0;
+}
@@ -1,39 +1,47 @@
-import { command, string } from "@drizzle-team/brocli";
+import { parseArgs } from "node:util";

-import { db, eq } from "@homarr/db";
+import { eq } from "drizzle-orm";
+
+import type { CliDatabase } from "../cli-db";
+import { getCliDb } from "../cli-db";
+import { CliError } from "../errors";
 import { users } from "@homarr/db/schema";

-export const usersDelete = command({
-  name: "delete",
-  desc: "Delete a user by id or username",
-  options: {
-    id: string("id").alias("i").desc("ID of the user"),
-    username: string("username").alias("u").desc("Name of the user"),
-  },
-  // eslint-disable-next-line no-restricted-syntax
-  handler: async (options) => {
-    if (!options.id && !options.username) {
-      console.error("Either --id or --username must be provided");
-      return;
-    }
+const userLookup: Record<"id" | "username", (db: CliDatabase, value: string) => Promise<{ id: string; name: string | null } | undefined>> = {
+  id: (db, value) =>
+    db.query.users.findFirst({
+      where: eq(users.id, value),
+    }),
+  username: (db, value) =>
+    db.query.users.findFirst({
+      where: eq(users.name, value),
+    }),
+};

-    let user;
-    if (options.id) {
-      user = await db.query.users.findFirst({
-        where: eq(users.id, options.id),
-      });
-    } else if (options.username) {
-      user = await db.query.users.findFirst({
-        where: eq(users.name, options.username),
-      });
-    }
+export async function usersDeleteHandler(args: string[]): Promise<number> {
+  const { values } = parseArgs({
+    args,
+    options: {
+      id: { type: "string", short: "i" },
+      username: { type: "string", short: "u" },
+    },
+  });

-    if (!user) {
-      console.error("User not found");
-      return;
-    }
+  const lookupKey = values.id ? "id" : values.username ? "username" : null;
+  const lookupValue = values.id ?? values.username;

-    await db.delete(users).where(eq(users.id, user.id));
-    console.log(`User ${user.name ?? user.id} (${user.id}) deleted`);
-  },
-});
+  if (!lookupKey || !lookupValue) {
+    throw new CliError("Either --id or --username must be provided", 2);
+  }
+
+  const db = getCliDb();
+  const user = await userLookup[lookupKey](db, lookupValue);
+
+  if (!user) {
+    throw new CliError("User not found");
+  }
+
+  await db.delete(users).where(eq(users.id, user.id));
+  console.log(`User ${user.name ?? user.id} (${user.id}) deleted`);
+  return 0;
+}
@@ -1,22 +1,35 @@
-import { command } from "@drizzle-team/brocli";
+import { parseArgs } from "node:util";

-import { db } from "@homarr/db";
+import { getCliDb } from "../cli-db";
+import { printTable } from "../utils";

-export const usersList = command({
-  name: "list",
-  desc: "List all users (id, username, email)",
-  // eslint-disable-next-line no-restricted-syntax
-  handler: async () => {
-    const allUsers = await db.query.users.findMany();
+export async function usersListHandler(args: string[] = []): Promise<number> {
+  const { values } = parseArgs({
+    args,
+    options: {
+      json: { type: "boolean", default: false },
+    },
+    strict: false,
+  });

-    if (allUsers.length === 0) {
-      console.log("No users found");
-      return;
-    }
+  const db = getCliDb();
+  const allUsers = await db.query.users.findMany();

-    console.log("ID\t\t\t\tUsername\tEmail");
-    for (const user of allUsers) {
-      console.log(`${user.id}\t${user.name ?? ""}\t${user.email ?? ""}`);
-    }
-  },
-});
+  if (values.json) {
+    const output = allUsers.map((u) => ({ id: u.id, name: u.name, email: u.email, provider: u.provider }));
+    console.log(JSON.stringify(output, null, 2));
+    return 0;
+  }
+
+  if (allUsers.length === 0) {
+    console.log("No users found");
+    return 0;
+  }
+
+  printTable(
+    ["ID", "Username", "Email", "Provider"],
+    allUsers.map((u) => [u.id, u.name ?? "", u.email ?? "", u.provider]),
+  );
+  console.log(`\n${allUsers.length} user(s) total`);
+  return 0;
+}
@@ -1,50 +1,66 @@
-import { command, string } from "@drizzle-team/brocli";
+import { parseArgs } from "node:util";

-import { hashPasswordAsync } from "@homarr/auth";
-import { db, eq } from "@homarr/db";
+import { hashPasswordAsync } from "@homarr/auth/security";
+import { eq } from "drizzle-orm";
+
+import type { CliDatabase } from "../cli-db";
+import { getCliDb } from "../cli-db";
+import { CliError, requireCredentialsProvider } from "../errors";
 import { sessions, users } from "@homarr/db/schema";

-export const usersUpdatePassword = command({
-  name: "update-password",
-  desc: "Update the password for a user (credentials provider only)",
-  options: {
-    id: string("id").alias("i").desc("ID of the user"),
-    username: string("username").alias("u").desc("Name of the user"),
-    password: string("password").alias("p").required().desc("New password"),
-  },
-  // eslint-disable-next-line no-restricted-syntax
-  handler: async (options) => {
-    if (!process.env.AUTH_PROVIDERS?.toLowerCase().includes("credentials")) {
-      console.error("Credentials provider is not enabled");
-      return;
-    }
+const userLookup: Record<
+  "id" | "username",
+  (db: CliDatabase, value: string) => Promise<{ id: string; name: string | null; password: string | null } | undefined>
+> = {
+  id: (db, value) =>
+    db.query.users.findFirst({
+      where: eq(users.id, value),
+    }),
+  username: (db, value) =>
+    db.query.users.findFirst({
+      where: eq(users.name, value),
+    }),
+};

-    if (!options.id && !options.username) {
-      console.error("Either --id or --username must be provided");
-      return;
-    }
+export async function usersUpdatePasswordHandler(args: string[]): Promise<number> {
+  requireCredentialsProvider();

-    const user = await db.query.users.findFirst({
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      where: options.id ? eq(users.id, options.id) : eq(users.name, options.username!),
-    });
+  const { values } = parseArgs({
+    args,
+    options: {
+      id: { type: "string", short: "i" },
+      username: { type: "string", short: "u" },
+      password: { type: "string", short: "p" },
+    },
+  });

-    if (!user?.password) {
-      console.error("User not found or has no credentials record");
-      return;
-    }
+  const lookupKey = values.id ? "id" : values.username ? "username" : null;
+  const lookupValue = values.id ?? values.username;

-    await db
-      .update(users)
-      .set({
-        password: await hashPasswordAsync(options.password),
-      })
-      .where(eq(users.id, user.id));
+  if (!lookupKey || !lookupValue) {
+    throw new CliError("Either --id or --username must be provided", 2);
+  }

-    // invalidate existing sessions
-    await db.delete(sessions).where(eq(sessions.userId, user.id));
-    console.log(`All sessions for user ${user.name ?? user.id} have been deleted`);
+  if (!values.password) {
+    throw new CliError("Missing required option: --password / -p", 2);
+  }

-    console.log("Password updated successfully");
-  },
-});
+  const db = getCliDb();
+  const user = await userLookup[lookupKey](db, lookupValue);
+
+  if (!user?.password) {
+    throw new CliError("User not found or has no credentials record");
+  }
+
+  await db
+    .update(users)
+    .set({
+      password: await hashPasswordAsync(values.password),
+    })
+    .where(eq(users.id, user.id));
+
+  await db.delete(sessions).where(eq(sessions.userId, user.id));
+  console.log(`All sessions for user ${user.name ?? user.id} have been deleted`);
+  console.log("Password updated successfully");
+  return 0;
+}
@@ -1,11 +0,0 @@
-import { command } from "@drizzle-team/brocli";
-
-import { usersDelete } from "./users-delete";
-import { usersList } from "./users-list";
-import { usersUpdatePassword } from "./users-update-password";
-
-export const usersRoot = command({
-  name: "users",
-  desc: "Group of commands to manage users",
-  subcommands: [usersList, usersDelete, usersUpdatePassword],
-});
@@ -0,0 +1,16 @@
+export class CliError extends Error {
+  constructor(
+    message: string,
+    readonly exitCode: 1 | 2 = 1,
+  ) {
+    super(message);
+    this.name = "CliError";
+  }
+}
+
+export const requireCredentialsProvider = () => {
+  const enabled = process.env.AUTH_PROVIDERS?.toLowerCase().includes("credentials") ?? false;
+  if (!enabled) {
+    throw new CliError("Credentials provider is not enabled");
+  }
+};
@@ -1,14 +1,41 @@
-import { run } from "@drizzle-team/brocli";
+import { closeCliDbAsync } from "./cli-db";
+import { CliError } from "./errors";
+import { runCliAsync } from "./router";

-import { fixUsernames } from "./commands/fix-usernames";
-import { integrationsRoot } from "./commands/integrations";
-import { recreateAdmin } from "./commands/recreate-admin";
-import { resetPassword } from "./commands/reset-password";
-import { usersRoot } from "./commands/users";
+const mainAsync = async (): Promise<number> => {
+  const argv = process.argv.slice(2);
+  const start = performance.now();

-const commands = [usersRoot, integrationsRoot, resetPassword, fixUsernames, recreateAdmin];
+  try {
+    const code = await runCliAsync(argv);
+    if (code === 0) {
+      const elapsed = Math.round(performance.now() - start);
+      console.error(`\nDone in ${elapsed}ms`);
+    }
+    return code;
+  } catch (error) {
+    if (error instanceof CliError) {
+      console.error(error.message);
+      return error.exitCode;
+    }

-void run(commands, {
-  name: "homarr-cli",
-  version: "1.0.0",
-});
+    if (error instanceof TypeError && error.message.startsWith("Unknown option")) {
+      console.error(error.message);
+      return 2;
+    }
+
+    console.error(error instanceof Error ? error.message : error);
+    return 1;
+  }
+};
+
+mainAsync()
+  .then(async (code) => {
+    await closeCliDbAsync();
+    process.exit(code);
+  })
+  .catch(async (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    await closeCliDbAsync();
+    process.exit(1);
+  });
@@ -0,0 +1,167 @@
+import { fixUsernamesHandler } from "./commands/fix-usernames";
+import { integrationsDeleteHandler } from "./commands/integrations-delete";
+import { integrationsListHandler } from "./commands/integrations-list";
+import { recreateAdminHandler } from "./commands/recreate-admin";
+import { resetPasswordHandler } from "./commands/reset-password";
+import { usersDeleteHandler } from "./commands/users-delete";
+import { usersListHandler } from "./commands/users-list";
+import { usersUpdatePasswordHandler } from "./commands/users-update-password";
+import { CliError } from "./errors";
+
+const VERSION = "1.0.0";
+
+type CommandHandler = (args: string[]) => Promise<number>;
+
+interface CommandDef {
+  handler: CommandHandler;
+  desc: string;
+  usage: string;
+}
+
+type CommandGroup = Record<string, CommandDef>;
+
+const topLevelCommands: Record<string, CommandDef> = {
+  "reset-password": {
+    handler: resetPasswordHandler,
+    desc: "Reset password for a credentials user",
+    usage: "homarr reset-password -u <username>",
+  },
+  "fix-usernames": {
+    handler: (args) => fixUsernamesHandler(),
+    desc: "Lowercase all credentials usernames",
+    usage: "homarr fix-usernames",
+  },
+  "recreate-admin": {
+    handler: recreateAdminHandler,
+    desc: "Create credentials admin if none exists",
+    usage: "homarr recreate-admin -u <username>",
+  },
+};
+
+const commandGroups: Record<string, CommandGroup> = {
+  users: {
+    list: {
+      handler: (args) => usersListHandler(args),
+      desc: "List all users",
+      usage: "homarr users list [--json]",
+    },
+    delete: {
+      handler: usersDeleteHandler,
+      desc: "Delete a user by id or username",
+      usage: "homarr users delete --id <id> | --username <name>",
+    },
+    "update-password": {
+      handler: usersUpdatePasswordHandler,
+      desc: "Set password for a credentials user",
+      usage: "homarr users update-password (--id <id> | --username <name>) --password <pw>",
+    },
+  },
+  integrations: {
+    list: {
+      handler: (args) => integrationsListHandler(args),
+      desc: "List all integrations",
+      usage: "homarr integrations list [--json]",
+    },
+    delete: {
+      handler: integrationsDeleteHandler,
+      desc: "Delete an integration by id or name",
+      usage: "homarr integrations delete --id <id> | --name <name>",
+    },
+  },
+};
+
+const HELP_TEXT = `homarr-cli ${VERSION}
+
+Usage:
+  homarr <command> [options]
+
+Commands:
+  reset-password         Reset password for a credentials user
+  recreate-admin         Create credentials admin if none exists
+  fix-usernames          Lowercase all credentials usernames
+  users list             List all users
+  users delete           Delete a user by id or username
+  users update-password  Set password for a credentials user
+  integrations list      List all integrations
+  integrations delete    Delete an integration by id or name
+
+Global Options:
+  -h, --help             Show help (use after a command for command-specific help)
+  -v, --version          Show CLI version
+`;
+
+const printHelp = () => {
+  console.log(HELP_TEXT);
+};
+
+const printCommandHelp = (def: CommandDef) => {
+  console.log(`${def.desc}\n`);
+  console.log(`Usage:\n  ${def.usage}\n`);
+};
+
+const resolveHandler = (argv: string[]): { handler: CommandHandler; args: string[] } => {
+  const [command, subcommand, ...rest] = argv;
+
+  if (!command) {
+    throw new CliError("Missing command", 2);
+  }
+
+  const group = commandGroups[command];
+  if (group) {
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+      const subcommands = Object.entries(group)
+        .map(([name, def]) => `  ${name.padEnd(18)} ${def.desc}`)
+        .join("\n");
+      console.log(`Usage:\n  homarr ${command} <subcommand> [options]\n\nSubcommands:\n${subcommands}\n`);
+      return { handler: async () => subcommand ? 0 : 2, args: [] };
+    }
+
+    const def = group[subcommand];
+    if (!def) {
+      throw new CliError(`Unknown subcommand "${subcommand}" for "${command}"`, 2);
+    }
+
+    if (hasFlag(rest, "--help", "-h")) {
+      printCommandHelp(def);
+      return { handler: async () => 0, args: [] };
+    }
+
+    return { handler: def.handler, args: rest };
+  }
+
+  const def = topLevelCommands[command];
+  if (!def) {
+    throw new CliError(`Unknown command "${command}"`, 2);
+  }
+
+  const args = argv.slice(1);
+  if (hasFlag(args, "--help", "-h")) {
+    printCommandHelp(def);
+    return { handler: async () => 0, args: [] };
+  }
+
+  return { handler: def.handler, args };
+};
+
+const hasFlag = (argv: string[], flag: string, short: string) =>
+  argv.some((arg) => arg === flag || arg === short);
+
+export const runCliAsync = async (argv: string[]): Promise<number> => {
+  if (hasFlag(argv, "--help", "-h") && argv.length === 1) {
+    printHelp();
+    return 0;
+  }
+
+  if (hasFlag(argv, "--version", "-v")) {
+    console.log(VERSION);
+    return 0;
+  }
+
+  if (argv.length === 0) {
+    printHelp();
+    return 2;
+  }
+
+  const { handler, args } = resolveHandler(argv);
+  return handler(args);
+};
@@ -0,0 +1,18 @@
+import { randomBytes } from "node:crypto";
+
+export const generateSecureRandomToken = (size: number) => randomBytes(size).toString("hex");
+
+export const printTable = (headers: string[], rows: string[][]) => {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)),
+  );
+
+  const formatRow = (cells: string[]) =>
+    cells.map((cell, i) => cell.padEnd(widths[i]!)).join("  ");
+
+  console.log(formatRow(headers));
+  console.log(widths.map((w) => "─".repeat(w)).join("  "));
+  for (const row of rows) {
+    console.log(formatRow(row));
+  }
+};
@@ -14,6 +14,7 @@
    "./infrastructure/db": "./src/infrastructure/db/index.ts",
    "./infrastructure/db/env": "./src/infrastructure/db/env.ts",
    "./infrastructure/db/constants": "./src/infrastructure/db/constants.ts",
+    "./infrastructure/db/mapping": "./src/infrastructure/db/mapping.ts",
    "./infrastructure/certificates": "./src/infrastructure/certificates/index.ts",
    "./infrastructure/certificates/hostnames/db/sqlite": "./src/infrastructure/certificates/hostnames/db/sqlite.ts",
    "./infrastructure/certificates/hostnames/db/mysql": "./src/infrastructure/certificates/hostnames/db/mysql.ts",
@@ -1,6 +1,6 @@
 import type { InferSelectModel } from "drizzle-orm";

-import { createSchema } from "@homarr/core/infrastructure/db";
+import { createDbMapping as createSchema } from "@homarr/core/infrastructure/db/mapping";

 import * as mysqlSchema from "./mysql";
 import * as pgSchema from "./postgresql";
@@ -61,7 +61,7 @@ export const integrationDefs = {
  },
  qBittorrent: {
    name: "qBittorrent",
-    secretKinds: [["username", "password"]],
+    secretKinds: [["apiKey"], ["username", "password"]],
    iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/qbittorrent.svg",
    category: ["downloadClient", "torrent"],
    documentationUrl: createDocumentationLink("/docs/integrations/q-bittorent"),
@@ -4,9 +4,11 @@ import { createBooleanSchema, createEnv } from "@homarr/core/infrastructure/env"

 export const env = createEnv({
  server: {
-    // Comma separated list of docker hostnames that can be used to connect to query the docker endpoints (localhost:2375,host.docker.internal:2375, ...)
+    // Comma separated list of docker hostnames that can be used to connect to query the docker endpoints (localhost,host.docker.internal, ...)
    DOCKER_HOSTNAMES: z.string().optional(),
    DOCKER_PORTS: z.string().optional(),
+    // Comma separated paths to Docker-compatible Unix sockets (e.g., /var/run/docker.sock,/run/user/1000/podman/podman.sock)
+    DOCKER_SOCKET_PATHS: z.string().optional(),
    ENABLE_DOCKER: createBooleanSchema(true),
    ENABLE_KUBERNETES: createBooleanSchema(false),
  },
@@ -11,31 +11,43 @@ export class DockerSingleton {
  private static instances: DockerInstance[] | null = null;

  private createInstances() {
+    const socketPaths = env.DOCKER_SOCKET_PATHS;
    const hostVariable = env.DOCKER_HOSTNAMES;
    const portVariable = env.DOCKER_PORTS;
-    if (hostVariable === undefined || portVariable === undefined) {
+
+    // Socket instances from DOCKER_SOCKET_PATHS
+    const socketInstances: DockerInstance[] = socketPaths
+      ? socketPaths.split(",").map((socketPath) => ({
+          host: socketPath,
+          instance: new Docker({ socketPath }),
+        }))
+      : [];
+
+    // TCP instances from existing DOCKER_HOSTNAMES/DOCKER_PORTS
+    let tcpInstances: DockerInstance[] = [];
+    if (hostVariable !== undefined && portVariable !== undefined) {
+      const hostnames = hostVariable.split(",");
+      const ports = portVariable.split(",");
+
+      if (hostnames.length !== ports.length) {
+        throw new Error("The number of hosts and ports must match");
+      }
+
+      tcpInstances = hostnames.map((host, i) => ({
+        host: `${host}:${ports[i]}`,
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        instance: new Docker({ host, port: parseInt(ports[i]!, 10) }),
+      }));
+    }
+
+    const instances = [...socketInstances, ...tcpInstances];
+
+    // Default: local socket if nothing else configured
+    if (instances.length === 0) {
      return [{ host: "socket", instance: new Docker() }];
    }
-    const hostnames = hostVariable.split(",");
-    const ports = portVariable.split(",");

-    if (hostnames.length !== ports.length) {
-      throw new Error("The number of hosts and ports must match");
-    }
-
-    return hostnames.map((host, i) => {
-      // Check above ensures that ports[i] is not undefined
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const port = ports[i]!;
-
-      return {
-        host: `${host}:${port}`,
-        instance: new Docker({
-          host,
-          port: parseInt(port, 10),
-        }),
-      };
-    });
+    return instances;
  }

  public static findInstance(host: string): DockerInstance | undefined {
@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import { DockerSingleton } from "../singleton";
+
+const mockEnv = vi.hoisted(() => ({
+  DOCKER_SOCKET_PATHS: undefined as string | undefined,
+  DOCKER_HOSTNAMES: undefined as string | undefined,
+  DOCKER_PORTS: undefined as string | undefined,
+  ENABLE_DOCKER: true,
+  ENABLE_KUBERNETES: false,
+}));
+
+vi.mock("dockerode", () => {
+  return {
+    default: class MockDocker {
+      constructor(public opts?: Record<string, unknown>) {}
+    },
+  };
+});
+
+vi.mock("../env", () => ({
+  env: mockEnv,
+}));
+
+describe("DockerSingleton", () => {
+  beforeEach(() => {
+    // Reset singleton cache between tests
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+    (DockerSingleton as any).instances = null;
+
+    // Reset env to defaults
+    mockEnv.DOCKER_SOCKET_PATHS = undefined;
+    mockEnv.DOCKER_HOSTNAMES = undefined;
+    mockEnv.DOCKER_PORTS = undefined;
+  });
+
+  test("should return default socket when no env vars set", () => {
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(1);
+    expect(instances[0]?.host).toBe("socket");
+  });
+
+  test("should return TCP instances only when DOCKER_HOSTNAMES and DOCKER_PORTS set", () => {
+    mockEnv.DOCKER_HOSTNAMES = "remote-host";
+    mockEnv.DOCKER_PORTS = "2375";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(1);
+    expect(instances[0]?.host).toBe("remote-host:2375");
+  });
+
+  test("should return multiple TCP instances", () => {
+    mockEnv.DOCKER_HOSTNAMES = "host1,host2";
+    mockEnv.DOCKER_PORTS = "2375,2376";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(2);
+    expect(instances[0]?.host).toBe("host1:2375");
+    expect(instances[1]?.host).toBe("host2:2376");
+  });
+
+  test("should throw when hostname and port counts do not match", () => {
+    mockEnv.DOCKER_HOSTNAMES = "host1,host2";
+    mockEnv.DOCKER_PORTS = "2375";
+
+    expect(() => DockerSingleton.getInstances()).toThrow("The number of hosts and ports must match");
+  });
+
+  test("should return socket instances when DOCKER_SOCKET_PATHS set", () => {
+    mockEnv.DOCKER_SOCKET_PATHS = "/var/run/docker.sock";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(1);
+    expect(instances[0]?.host).toBe("/var/run/docker.sock");
+  });
+
+  test("should return multiple socket instances", () => {
+    mockEnv.DOCKER_SOCKET_PATHS = "/var/run/docker.sock,/run/user/1000/podman/podman.sock";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(2);
+    expect(instances[0]?.host).toBe("/var/run/docker.sock");
+    expect(instances[1]?.host).toBe("/run/user/1000/podman/podman.sock");
+  });
+
+  test("should combine socket and TCP instances", () => {
+    mockEnv.DOCKER_SOCKET_PATHS = "/var/run/docker.sock,/run/user/1000/podman/podman.sock";
+    mockEnv.DOCKER_HOSTNAMES = "remote-host";
+    mockEnv.DOCKER_PORTS = "2375";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(3);
+    expect(instances[0]?.host).toBe("/var/run/docker.sock");
+    expect(instances[1]?.host).toBe("/run/user/1000/podman/podman.sock");
+    expect(instances[2]?.host).toBe("remote-host:2375");
+  });
+
+  test("should cache instances on subsequent calls", () => {
+    const first = DockerSingleton.getInstances();
+    const second = DockerSingleton.getInstances();
+
+    expect(first).toBe(second);
+  });
+});
@@ -90,10 +90,18 @@ export class QBitTorrentIntegration extends Integration implements IDownloadClie
  }

  private async getClientAsync(dispatcher?: Dispatcher) {
+    const credentials = this.hasSecretValue("apiKey")
+      ? {
+          apiKey: this.getSecretValue("apiKey"),
+        }
+      : {
+          username: this.getSecretValue("username"),
+          password: this.getSecretValue("password"),
+        };
+
    return new QBittorrent({
+      ...credentials,
      baseUrl: this.url("/").toString(),
-      username: this.getSecretValue("username"),
-      password: this.getSecretValue("password"),
      dispatcher: dispatcher ?? (await createCertificateAgentAsync()),
    });
  }
@@ -2,6 +2,8 @@ import dayjs from "dayjs";
 import type { ContainerInfo, ContainerStats } from "dockerode";
 import type Dockerode from "dockerode";

+import { createLogger } from "@homarr/core/infrastructure/logs";
+import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
 import { db, like, or } from "@homarr/db";
 import { icons } from "@homarr/db/schema";
 import type { ContainerState } from "@homarr/docker";
@@ -9,6 +11,8 @@ import { dockerLabels, DockerSingleton } from "@homarr/docker";

 import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";

+const logger = createLogger({ module: "dockerRequestHandler" });
+
 export const dockerContainersRequestHandler = createCachedWidgetRequestHandler({
  queryKey: "dockerContainersResult",
  widgetKind: "dockerContainers",
@@ -18,19 +22,34 @@ export const dockerContainersRequestHandler = createCachedWidgetRequestHandler({
  cacheDuration: dayjs.duration(20, "seconds"),
 });

-const dockerInstances = DockerSingleton.getInstances();
-
 const extractImage = (container: ContainerInfo) => container.Image.split("/").at(-1)?.split(":").at(0) ?? "";

 async function getContainersWithStatsAsync() {
-  const containers = await Promise.all(
+  const dockerInstances = DockerSingleton.getInstances();
+  const results = await Promise.allSettled(
    dockerInstances.map(async ({ instance, host }) => {
      const instanceContainers = await instance.listContainers({ all: true });
      return instanceContainers
        .filter((container) => !(dockerLabels.hide in container.Labels))
        .map((container) => ({ ...container, instance: host }));
    }),
-  ).then((res) => res.flat());
+  );
+
+  const containers = results.flatMap((result, index) => {
+    if (result.status === "fulfilled") return result.value;
+    logger.warn(
+      new ErrorWithMetadata(
+        "Failed to list containers from Docker host",
+        {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          host: dockerInstances[index]!.host,
+        },
+        { cause: result.reason },
+      ),
+    );
+
+    return [];
+  });
  const likeQueries = containers.map((container) => like(icons.name, `%${extractImage(container)}%`));

  const dbIcons =
@@ -44,8 +63,6 @@ async function getContainersWithStatsAsync() {
    const instance = dockerInstances.find(({ host }) => host === container.instance)?.instance;
    if (!instance) return null;

-    // Get stats, falling back to an empty stats object if fetch fails
-    // calculateCpuUsage and calculateMemoryUsage will return 0 for invalid/missing stats
    const stats = await instance
      .getContainer(container.Id)
      .stats({ stream: false, "one-shot": true })
@@ -63,6 +80,7 @@ async function getContainersWithStatsAsync() {
    return {
      id: container.Id,
      name: container.Names[0]?.split("/")[1] ?? "Unknown",
+      host: container.instance,
      state: container.State as ContainerState,
      iconUrl:
        dbIcons.find((icon) => {
@@ -80,9 +98,10 @@ async function getContainersWithStatsAsync() {
  return (await Promise.all(containerStatsPromises)).filter((container) => container !== null);
 }

-function calculateCpuUsage(stats: ContainerStats): number {
-  // Handle containers with missing or invalid stats (e.g., exited, dead containers)
-  if (!stats.cpu_stats.online_cpus || stats.cpu_stats.online_cpus === 0 || !stats.cpu_stats.cpu_usage.total_usage) {
+export function calculateCpuUsage(stats: ContainerStats): number {
+  // Handle containers with missing or invalid stats (e.g., exited, dead containers, Podman responses)
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!stats.cpu_stats?.online_cpus || stats.cpu_stats.online_cpus === 0 || !stats.cpu_stats.cpu_usage?.total_usage) {
    return 0;
  }

@@ -95,9 +114,10 @@ function calculateCpuUsage(stats: ContainerStats): number {
  return (stats.cpu_stats.cpu_usage.total_usage / usage) * numberOfCpus * 100;
 }

-function calculateMemoryUsage(stats: ContainerStats): number {
-  // Handle containers with missing or invalid stats (e.g., exited, dead containers)
-  if (!stats.memory_stats.usage) {
+export function calculateMemoryUsage(stats: ContainerStats): number {
+  // Handle containers with missing or invalid stats (e.g., exited, dead containers, Podman responses)
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!stats.memory_stats?.usage) {
    return 0;
  }

@@ -0,0 +1,121 @@
+import type { ContainerStats } from "dockerode";
+import { describe, expect, test, vi } from "vitest";
+
+import { createDb } from "@homarr/db/test";
+
+import { calculateCpuUsage, calculateMemoryUsage } from "../docker";
+
+vi.mock("@homarr/db", async (importActual) => {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+  const actual = await importActual<typeof import("@homarr/db")>();
+  return {
+    ...actual,
+    db: createDb(),
+  };
+});
+
+// Helper to create a partial stats object, cast to ContainerStats.
+// This mirrors what Podman and other Docker-compatible runtimes may return
+// at runtime, even though @types/dockerode declares all fields as required.
+const createStats = (overrides: Record<string, unknown> = {}) => overrides as unknown as ContainerStats;
+
+describe("calculateCpuUsage", () => {
+  test("should return 0 when cpu_stats is undefined (Podman)", () => {
+    const stats = createStats({ cpu_stats: undefined });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when online_cpus is 0", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 0, cpu_usage: { total_usage: 1000 }, system_cpu_usage: 5000 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when online_cpus is undefined", () => {
+    const stats = createStats({
+      cpu_stats: { cpu_usage: { total_usage: 1000 }, system_cpu_usage: 5000 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when cpu_usage is undefined", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, system_cpu_usage: 5000 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when total_usage is 0", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 0 }, system_cpu_usage: 5000 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when system_cpu_usage is 0", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 1000 }, system_cpu_usage: 0 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should calculate correct CPU percentage for valid stats", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 2000 }, system_cpu_usage: 10000 },
+    });
+    // (2000 / 10000) * 4 * 100 = 80
+    expect(calculateCpuUsage(stats)).toBe(80);
+  });
+
+  test("should handle fractional CPU usage", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 2, cpu_usage: { total_usage: 500 }, system_cpu_usage: 100000 },
+    });
+    // (500 / 100000) * 2 * 100 = 1
+    expect(calculateCpuUsage(stats)).toBe(1);
+  });
+});
+
+describe("calculateMemoryUsage", () => {
+  test("should return 0 when memory_stats is undefined (Podman)", () => {
+    const stats = createStats({ memory_stats: undefined });
+    expect(calculateMemoryUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when memory_stats.usage is 0", () => {
+    const stats = createStats({ memory_stats: { usage: 0 } });
+    expect(calculateMemoryUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when memory_stats.usage is undefined", () => {
+    const stats = createStats({ memory_stats: {} });
+    expect(calculateMemoryUsage(stats)).toBe(0);
+  });
+
+  test("should subtract cache from usage", () => {
+    const stats = createStats({
+      memory_stats: { usage: 1000, stats: { cache: 200 } },
+    });
+    expect(calculateMemoryUsage(stats)).toBe(800);
+  });
+
+  test("should use total_inactive_file when cache is absent", () => {
+    const stats = createStats({
+      memory_stats: { usage: 1000, stats: { total_inactive_file: 300 } },
+    });
+    expect(calculateMemoryUsage(stats)).toBe(700);
+  });
+
+  test("should use inactive_file as last fallback", () => {
+    const stats = createStats({
+      memory_stats: { usage: 1000, stats: { inactive_file: 150 } },
+    });
+    expect(calculateMemoryUsage(stats)).toBe(850);
+  });
+
+  test("should return raw usage when memory_stats.stats is undefined", () => {
+    const stats = createStats({ memory_stats: { usage: 512 } });
+    expect(calculateMemoryUsage(stats)).toBe(512);
+  });
+});
@@ -3970,6 +3970,9 @@
      },
      "ports": {
        "label": "Ports"
+      },
+      "host": {
+        "label": "Host"
      }
    },
    "action": {
@@ -79,6 +79,19 @@ const createColumns = (
      return <ContainerStateBadge state={row.original.state} />;
    },
  },
+  {
+    id: "host",
+    accessorKey: "host",
+    size: 100,
+    header: t("field.host.label"),
+    Cell({ row }) {
+      return (
+        <Text size="xs" truncate="end">
+          {row.original.host}
+        </Text>
+      );
+    },
+  },
  {
    id: "cpuUsage",
    sortingFn: (rowA, rowB) => {
@@ -65,8 +65,8 @@ const columnsRatios: Record<keyof ExtendedDownloadClientItem, number> = {
  id: 1,
  index: 1,
  integration: 1,
-  name: 8,
-  progress: 4,
+  name: 16,
+  progress: 6,
  ratio: 2,
  received: 3,
  sent: 3,
@@ -2,35 +2,19 @@ packages:
  - apps/*
  - packages/*
  - tooling/*
-allowBuilds:
-  "@scarf/scarf": false
-  "@swc/core": false
-  "@tree-sitter-grammars/tree-sitter-yaml": true
-  bcrypt: true
-  better-sqlite3: true
-  core-js-pure: false
-  cpu-features: true
-  esbuild: true
-  protobufjs: false
-  sharp: true
-  ssh2: true
-  tree-sitter: true
-  tree-sitter-json: true
-  nice-napi: false
-allowUnusedPatches: true
 catalog:
  "@auth/core": ^0.41.2
  "@auth/drizzle-adapter": ^1.11.2
  "@ctrl/deluge": ^8.0.0
-  "@ctrl/qbittorrent": ^9.11.2
+  "@ctrl/qbittorrent": ^9.12.1
  "@ctrl/transmission": ^7.4.0
  "@dnd-kit/core": ^6.3.1
  "@dnd-kit/modifiers": ^9.0.0
  "@dnd-kit/sortable": ^10.0.0
  "@dnd-kit/utilities": ^3.2.2
  "@drizzle-team/brocli": ^0.12.0
-  "@eslint/js": 10.0.1
-  "@extractus/feed-extractor": 7.1.7
+  '@eslint/js': 10.0.1
+  "@extractus/feed-extractor": 7.2.1
  "@gitbeaker/rest": ^43.8.0
  "@homarr/gridstack": ^1.12.0
  "@homarr/node-unifi": ^2.6.0
@@ -61,9 +45,9 @@ catalog:
  "@semantic-release/release-notes-generator": ^14.1.0
  "@t3-oss/env-nextjs": ^0.13.11
  "@tabler/icons-react": ^3.41.1
-  "@tanstack/react-query": ^5.100.8
-  "@tanstack/react-query-devtools": ^5.100.8
-  "@tanstack/react-query-next-experimental": ^5.100.8
+  "@tanstack/react-query": ^5.100.9
+  "@tanstack/react-query-devtools": ^5.100.9
+  "@tanstack/react-query-next-experimental": ^5.100.9
  "@testcontainers/mysql": ^11.14.0
  "@testcontainers/postgresql": ^11.14.0
  "@testcontainers/redis": ^11.14.0
@@ -88,7 +72,7 @@ catalog:
  "@trpc/react-query": ^11.17.0
  "@trpc/server": ^11.17.0
  "@trpc/tanstack-react-query": ^11.17.0
-  "@turbo/gen": ^2.9.7
+  "@turbo/gen": ^2.9.8
  "@types/adm-zip": 0.5.8
  "@types/bcrypt": 6.0.0
  "@types/better-sqlite3": 7.6.13
@@ -139,7 +123,7 @@ catalog:
  esbuild: ^0.28.0
  eslint: ^10.3.0
  eslint-config-prettier: ^10.1.8
-  eslint-config-turbo: ^2.9.7
+  eslint-config-turbo: ^2.9.8
  eslint-plugin-import: ^2.32.0
  eslint-plugin-jsx-a11y: ^6.10.2
  eslint-plugin-react: ^7.37.5
@@ -189,7 +173,7 @@ catalog:
  trpc-to-openapi: ^3.2.0
  tsdav: ^2.2.0
  tsx: 4.20.4
-  turbo: ^2.9.7
+  turbo: ^2.9.8
  typescript: ^5.9.3
  typescript-eslint: ^8.58.2
  undici: 7.24.6
@@ -201,36 +185,11 @@ catalog:
  ws: ^8.20.0
  xml2js: ^0.6.2
  yaml: 2.8.4
-  zod: ^4.4.2
+  zod: ^4.4.3
  zod-form-data: ^3.0.1
  zod-validation-error: ^5.0.0
 catalogMode: strict
-engineStrict: true
 minimumReleaseAge: 4320
 minimumReleaseAgeExclude:
  - next
  - "@next/*"
-nodeLinker: hoisted
-overrides:
-  "@babel/helpers@<7.26.10": ">=7.29.2"
-  "@babel/runtime@<7.26.10": ">=7.29.2"
-  "axios@>=1.0.0 <1.8.2": ">=1.16.0"
-  "brace-expansion@>=1.0.0 <=1.1.11": ">=5.0.5"
-  "brace-expansion@>=2.0.0 <=2.0.1": ">=5.0.5"
-  "esbuild@<=0.24.2": ">=0.28.0"
-  "form-data@>=4.0.0 <4.0.4": ">=4.0.5"
-  "hono@<4.6.5": ">=4.12.16"
-  "linkifyjs@<4.3.2": ">=4.3.2"
-  "nanoid@>=4.0.0 <5.0.9": ">=5.1.11"
-  "prismjs@<1.30.0": ">=1.30.0"
-  "proxmox-api>undici": "7.24.6"
-  "react-is": "^19.2.5"
-  "rollup@>=4.0.0 <4.22.4": ">=4.60.2"
-  "sha.js@<=2.4.11": ">=2.4.12"
-  "tar-fs@>=2.0.0 <2.1.3": ">=3.1.2"
-  "tar-fs@>=3.0.0 <3.0.9": ">=3.1.2"
-  "tmp@<=0.2.3": ">=0.2.5"
-  "vite@>=5.0.0 <=5.4.18": ">=8.0.10"
-patchedDependencies:
-  "@types/node-unifi": "patches/@types__node-unifi.patch"
-  trpc-to-openapi: "patches/trpc-to-openapi.patch"
@@ -18,6 +18,19 @@ if [ "${PUID}" != "0" ] || [ "${PGID}" != "0" ]; then
    echo "Changing owner to $PUID:$PGID, done."
 fi

+# support _FILE Suffix for environment variables
+for file_var in $(env | cut -d '=' -f 1 | grep "_FILE$"); do
+    target_var=$(echo "$file_var" | cut -d'=' -f1 | sed 's/_FILE//')
+    file_path=$(printenv "$file_var")
+
+    if [ -f "$file_path" ]; then
+        export "$target_var"=$(cat "$file_path" | tr -d '\n\r')
+        echo "Info: Loaded secret for $target_var from $file_path"
+    else
+        echo "Warning: Secret file $file_path not found for $target_var"
+    fi
+done
+
 if [ "${PUID}" != "0" ]; then
    exec su-exec $PUID:$PGID "$@"
 else
@@ -19,11 +19,6 @@ export AUTH_SECRET=$(openssl rand -base64 32)
 # Cron job API key is generated every time the container starts as it is required for communication between nextjs-api and tasks-api
 export CRON_JOB_API_KEY=$(openssl rand -base64 32)

-# Support secret file for encryption key (is not empty and file exists)
-if [ -n "$SECRET_ENCRYPTION_KEY_FILE" ] && [ -f "$SECRET_ENCRYPTION_KEY_FILE" ]; then
-    export SECRET_ENCRYPTION_KEY=$(cat $SECRET_ENCRYPTION_KEY_FILE)
-fi
-
 # Start nginx proxy
 # 1. Replace the HOSTNAME in the nginx template file
 # 2. Create the nginx configuration file from the template
@@ -1 +1 @@
-[{"login":"ajnart","avatar_url":"https://avatars.githubusercontent.com/u/49837342?v=4"},{"login":"manuel-rw","avatar_url":"https://avatars.githubusercontent.com/u/30572287?v=4"},{"login":"Meierschlumpf","avatar_url":"https://avatars.githubusercontent.com/u/63781622?v=4"},{"login":"SeDemal","avatar_url":"https://avatars.githubusercontent.com/u/26098587?v=4"},{"login":"lammersbjorn","avatar_url":"https://avatars.githubusercontent.com/u/71191962?v=4"},{"login":"LarveyOfficial","avatar_url":"https://avatars.githubusercontent.com/u/39219859?v=4"},{"login":"c00ldude1oo","avatar_url":"https://avatars.githubusercontent.com/u/15677803?v=4"},{"login":"InterN0te","avatar_url":"https://avatars.githubusercontent.com/u/10882916?v=4"},{"login":"Aimsucks","avatar_url":"https://avatars.githubusercontent.com/u/1828486?v=4"},{"login":"JannesV","avatar_url":"https://avatars.githubusercontent.com/u/5984244?v=4"},{"login":"MauriceNino","avatar_url":"https://avatars.githubusercontent.com/u/18658092?v=4"},{"login":"hillaliy","avatar_url":"https://avatars.githubusercontent.com/u/950010?v=4"},{"login":"Skeeww","avatar_url":"https://avatars.githubusercontent.com/u/9639992?v=4"},{"login":"RichyHBM","avatar_url":"https://avatars.githubusercontent.com/u/5472275?v=4"},{"login":"Bonfire","avatar_url":"https://avatars.githubusercontent.com/u/5704760?v=4"},{"login":"wieli99","avatar_url":"https://avatars.githubusercontent.com/u/46794825?v=4"},{"login":"ishaanparlikar","avatar_url":"https://avatars.githubusercontent.com/u/43013132?v=4"},{"login":"Zareix","avatar_url":"https://avatars.githubusercontent.com/u/29818713?v=4"},{"login":"tuggan","avatar_url":"https://avatars.githubusercontent.com/u/4325608?v=4"},{"login":"Spillebulle","avatar_url":"https://avatars.githubusercontent.com/u/46653946?v=4"},{"login":"spkesDE","avatar_url":"https://avatars.githubusercontent.com/u/1682314?v=4"},{"login":"j3lte","avatar_url":"https://avatars.githubusercontent.com/u/2557568?v=4"},{"login":"dslatt","avatar_url":"https://avatars.githubusercontent.com/u/5211001?v=4"},{"login":"Malong11-007","avatar_url":"https://avatars.githubusercontent.com/u/40298510?v=4"},{"login":"StefanB7","avatar_url":"https://avatars.githubusercontent.com/u/22056509?v=4"},{"login":"souravghosh01","avatar_url":"https://avatars.githubusercontent.com/u/37548139?v=4"},{"login":"SR3u","avatar_url":"https://avatars.githubusercontent.com/u/2380522?v=4"},{"login":"Rikpat","avatar_url":"https://avatars.githubusercontent.com/u/33869814?v=4"},{"login":"NormanJS","avatar_url":"https://avatars.githubusercontent.com/u/83409549?v=4"},{"login":"No-Maines-Land","avatar_url":"https://avatars.githubusercontent.com/u/20687725?v=4"},{"login":"stark1tty","avatar_url":"https://avatars.githubusercontent.com/u/69326376?v=4"},{"login":"Momcilo42","avatar_url":"https://avatars.githubusercontent.com/u/10118137?v=4"},{"login":"marius-arch","avatar_url":"https://avatars.githubusercontent.com/u/72494359?v=4"},{"login":"Lumilias","avatar_url":"https://avatars.githubusercontent.com/u/10852161?v=4"},{"login":"Havock94","avatar_url":"https://avatars.githubusercontent.com/u/7635248?v=4"},{"login":"Lollyde","avatar_url":"https://avatars.githubusercontent.com/u/11347524?v=4"},{"login":"krishnamuppaneni","avatar_url":"https://avatars.githubusercontent.com/u/4703366?v=4"},{"login":"devtobi","avatar_url":"https://avatars.githubusercontent.com/u/28538704?v=4"},{"login":"TyxTang","avatar_url":"https://avatars.githubusercontent.com/u/90897955?v=4"},{"login":"alotlikebeans","avatar_url":"https://avatars.githubusercontent.com/u/19630511?v=4"},{"login":"WillyJL","avatar_url":"https://avatars.githubusercontent.com/u/49810075?v=4"},{"login":"anonysoul","avatar_url":"https://avatars.githubusercontent.com/u/105715150?v=4"},{"login":"cospeedster","avatar_url":"https://avatars.githubusercontent.com/u/52749645?v=4"},{"login":"diederbert","avatar_url":"https://avatars.githubusercontent.com/u/162878798?v=4"},{"login":"digdilem","avatar_url":"https://avatars.githubusercontent.com/u/4052275?v=4"},{"login":"dinghino","avatar_url":"https://avatars.githubusercontent.com/u/14729459?v=4"},{"login":"gfomichev","avatar_url":"https://avatars.githubusercontent.com/u/1596146?v=4"},{"login":"gnattu","avatar_url":"https://avatars.githubusercontent.com/u/12995396?v=4"},{"login":"tuxpizza","avatar_url":"https://avatars.githubusercontent.com/u/84710786?v=4"},{"login":"xmarkurion","avatar_url":"https://avatars.githubusercontent.com/u/46654687?v=4"},{"login":"huanga","avatar_url":"https://avatars.githubusercontent.com/u/732970?v=4"},{"login":"taos15","avatar_url":"https://avatars.githubusercontent.com/u/122130728?v=4"},{"login":"arghyadipchak","avatar_url":"https://avatars.githubusercontent.com/u/32430374?v=4"},{"login":"AuthorShin","avatar_url":"https://avatars.githubusercontent.com/u/4959043?v=4"},{"login":"benniblot","avatar_url":"https://avatars.githubusercontent.com/u/47495914?v=4"},{"login":"bebsworthy","avatar_url":"https://avatars.githubusercontent.cLine truncated
+[{"login":"ajnart","avatar_url":"https://avatars.githubusercontent.com/u/49837342?v=4"},{"login":"manuel-rw","avatar_url":"https://avatars.githubusercontent.com/u/30572287?v=4"},{"login":"Meierschlumpf","avatar_url":"https://avatars.githubusercontent.com/u/63781622?v=4"},{"login":"SeDemal","avatar_url":"https://avatars.githubusercontent.com/u/26098587?v=4"},{"login":"lammersbjorn","avatar_url":"https://avatars.githubusercontent.com/u/71191962?v=4"},{"login":"LarveyOfficial","avatar_url":"https://avatars.githubusercontent.com/u/39219859?v=4"},{"login":"c00ldude1oo","avatar_url":"https://avatars.githubusercontent.com/u/15677803?v=4"},{"login":"InterN0te","avatar_url":"https://avatars.githubusercontent.com/u/10882916?v=4"},{"login":"Aimsucks","avatar_url":"https://avatars.githubusercontent.com/u/1828486?v=4"},{"login":"JannesV","avatar_url":"https://avatars.githubusercontent.com/u/5984244?v=4"},{"login":"MauriceNino","avatar_url":"https://avatars.githubusercontent.com/u/18658092?v=4"},{"login":"hillaliy","avatar_url":"https://avatars.githubusercontent.com/u/950010?v=4"},{"login":"Skeeww","avatar_url":"https://avatars.githubusercontent.com/u/9639992?v=4"},{"login":"RichyHBM","avatar_url":"https://avatars.githubusercontent.com/u/5472275?v=4"},{"login":"Bonfire","avatar_url":"https://avatars.githubusercontent.com/u/5704760?v=4"},{"login":"wieli99","avatar_url":"https://avatars.githubusercontent.com/u/46794825?v=4"},{"login":"ishaanparlikar","avatar_url":"https://avatars.githubusercontent.com/u/43013132?v=4"},{"login":"Zareix","avatar_url":"https://avatars.githubusercontent.com/u/29818713?v=4"},{"login":"tuggan","avatar_url":"https://avatars.githubusercontent.com/u/4325608?v=4"},{"login":"Spillebulle","avatar_url":"https://avatars.githubusercontent.com/u/46653946?v=4"},{"login":"spkesDE","avatar_url":"https://avatars.githubusercontent.com/u/1682314?v=4"},{"login":"j3lte","avatar_url":"https://avatars.githubusercontent.com/u/2557568?v=4"},{"login":"dslatt","avatar_url":"https://avatars.githubusercontent.com/u/5211001?v=4"},{"login":"Malong11-007","avatar_url":"https://avatars.githubusercontent.com/u/40298510?v=4"},{"login":"StefanB7","avatar_url":"https://avatars.githubusercontent.com/u/22056509?v=4"},{"login":"souravghosh01","avatar_url":"https://avatars.githubusercontent.com/u/37548139?v=4"},{"login":"SR3u","avatar_url":"https://avatars.githubusercontent.com/u/2380522?v=4"},{"login":"Rikpat","avatar_url":"https://avatars.githubusercontent.com/u/33869814?v=4"},{"login":"NormanJS","avatar_url":"https://avatars.githubusercontent.com/u/83409549?v=4"},{"login":"No-Maines-Land","avatar_url":"https://avatars.githubusercontent.com/u/20687725?v=4"},{"login":"stark1tty","avatar_url":"https://avatars.githubusercontent.com/u/69326376?v=4"},{"login":"Momcilo42","avatar_url":"https://avatars.githubusercontent.com/u/10118137?v=4"},{"login":"marius-arch","avatar_url":"https://avatars.githubusercontent.com/u/72494359?v=4"},{"login":"Lumilias","avatar_url":"https://avatars.githubusercontent.com/u/10852161?v=4"},{"login":"Havock94","avatar_url":"https://avatars.githubusercontent.com/u/7635248?v=4"},{"login":"Lollyde","avatar_url":"https://avatars.githubusercontent.com/u/11347524?v=4"},{"login":"krishnamuppaneni","avatar_url":"https://avatars.githubusercontent.com/u/4703366?v=4"},{"login":"devtobi","avatar_url":"https://avatars.githubusercontent.com/u/28538704?v=4"},{"login":"TyxTang","avatar_url":"https://avatars.githubusercontent.com/u/90897955?v=4"},{"login":"alotlikebeans","avatar_url":"https://avatars.githubusercontent.com/u/19630511?v=4"},{"login":"WillyJL","avatar_url":"https://avatars.githubusercontent.com/u/49810075?v=4"},{"login":"anonysoul","avatar_url":"https://avatars.githubusercontent.com/u/105715150?v=4"},{"login":"cospeedster","avatar_url":"https://avatars.githubusercontent.com/u/52749645?v=4"},{"login":"diederbert","avatar_url":"https://avatars.githubusercontent.com/u/162878798?v=4"},{"login":"digdilem","avatar_url":"https://avatars.githubusercontent.com/u/4052275?v=4"},{"login":"dinghino","avatar_url":"https://avatars.githubusercontent.com/u/14729459?v=4"},{"login":"gfomichev","avatar_url":"https://avatars.githubusercontent.com/u/1596146?v=4"},{"login":"gnattu","avatar_url":"https://avatars.githubusercontent.com/u/12995396?v=4"},{"login":"tuxpizza","avatar_url":"https://avatars.githubusercontent.com/u/84710786?v=4"},{"login":"xmarkurion","avatar_url":"https://avatars.githubusercontent.com/u/46654687?v=4"},{"login":"huanga","avatar_url":"https://avatars.githubusercontent.com/u/732970?v=4"},{"login":"taos15","avatar_url":"https://avatars.githubusercontent.com/u/122130728?v=4"},{"login":"arghyadipchak","avatar_url":"https://avatars.githubusercontent.com/u/32430374?v=4"},{"login":"AuthorShin","avatar_url":"https://avatars.githubusercontent.com/u/4959043?v=4"},{"login":"benniblot","avatar_url":"https://avatars.githubusercontent.com/u/47495914?v=4"},{"login":"bebsworthy","avatar_url":"https://avatars.githubusercontent.cLine truncated
@@ -2,24 +2,21 @@ import fs from "fs/promises";
 import { join } from "path";
 import json5 from "json5";
 import { describe, test } from "vitest";
-import { parse as parseYaml } from "yaml";

 describe("Renovate configuration tests", () => {
-  test("automerge should be disabled for built dependencies", async () => {
-    const pnpmConfig = await fs.readFile(join(__dirname, "../pnpm-workspace.yaml"), "utf-8").then(parseYaml);
+  test("automerge should be disabled for onlyBuiltDependencies", async () => {
+    const packageJson = await import("../package.json");
    const renovateConfig = await fs.readFile(join(__dirname, "../.github/renovate.json5"), "utf-8").then(json5.parse);
-    const dependenciesWithBuilt = Object.entries(pnpmConfig.allowBuilds)
-      .filter(([_, value]) => value === true)
-      .map(([key, _]) => key);
+    const onlyBuiltDependencies = packageJson.pnpm.onlyBuiltDependencies;
    const automergeDisabledDeps = renovateConfig.packageRules
      .filter((rule: any) => rule.automerge === false)
      .flatMap((rule: any) => rule.matchPackageNames || []);

-    const missingDeps = dependenciesWithBuilt.filter((dep: string) => !automergeDisabledDeps.includes(dep));
+    const missingDeps = onlyBuiltDependencies.filter((dep: string) => !automergeDisabledDeps.includes(dep));

    if (missingDeps.length > 0) {
      throw new Error(
-        `The following built dependencies are missing automerge disable rules in renovate.json5: ${missingDeps.join(", ")}`,
+        `The following onlyBuiltDependencies are missing automerge disable rules in renovate.json5: ${missingDeps.join(", ")}`,
      );
    }
  });
@@ -37,6 +37,7 @@
    "DB_DRIVER",
    "DOCKER_HOSTNAMES",
    "DOCKER_PORTS",
+    "DOCKER_SOCKET_PATHS",
    "NODE_ENV",
    "PORT",
    "LOCAL_CERTIFICATE_PATH",
Author	SHA1	Message	Date
Thomas Camlong	3dc382145c	refactor(cli): rewrite CLI for reliability and better UX Replace brocli framework with Node's built-in util.parseArgs and a declarative command registry. The CLI no longer hangs after completing because: - DB connections are lazily created and explicitly closed - Winston/Redis logging is excluded from the bundle entirely - process.exit() is always called with proper exit codes Additional improvements: - Bundle size reduced from 5.3MB to 1.2MB (native drivers externalized) - Proper column-aligned table output for list commands - --json flag on list commands for scripting/automation - Per-command --help with usage examples - Execution timing shown on success - Consistent exit codes (0=success, 1=error, 2=usage) - Docker wrapper sets DISABLE_REDIS_LOGS and uses exec	2026-05-21 16:05:27 +02:00
Releases Homarr	48ef8eb6c0	chore(release): 1.61.1 [skip ci]	2026-05-18 19:45:44 +00:00
Austin	e9142c0dbc	fix(downloads-widget): increase name column default width ratio	2026-05-18 21:44:47 +02:00
Releases Homarr	4635c51fe1	chore(release): 1.61.0 [skip ci]	2026-05-08 20:06:52 +00:00
homarr-releases[bot]	5cc0f97aa2	chore(release): automatic release v1.61.0	2026-05-08 20:05:49 +00:00
homarr-renovate[bot]	b581f9b11a	chore(deps): update dependency @extractus/feed-extractor to v7.2.1 (#5670 ) Co-authored-by: homarr-renovate[bot] <158783068+homarr-renovate[bot]@users.noreply.github.com>	2026-05-08 19:26:12 +00:00
Meier Lukas	756e8d1724	feat(qbittorrent): add api-key support (#5677 )	2026-05-08 20:08:37 +02:00
homarr-renovate[bot]	7c64de5cbc	chore(deps): update turbo monorepo to ^2.9.8 (#5669 ) Co-authored-by: homarr-renovate[bot] <158783068+homarr-renovate[bot]@users.noreply.github.com>	2026-05-08 17:25:39 +00:00
Ashton BattyandMeier Lukas	56af6bcaf0	feat(docker): Podman compatibility, multi-socket support, per-host error isolation (#5425 ) Co-authored-by: Meier Lukas <meierschlumpf@gmail.com>	2026-05-08 17:31:56 +02:00
homarr-renovate[bot]	84b269a80d	chore(deps): update tanstack-query monorepo to ^5.100.9 (#5678 ) Co-authored-by: homarr-renovate[bot] <158783068+homarr-renovate[bot]@users.noreply.github.com>	2026-05-08 15:30:26 +00:00
Borislaw SotnikowandMeier Lukas	4d30a2e8c4	feat(installations): support secrets file for all environment variables (#5125 ) Co-authored-by: Meier Lukas <meierschlumpf@gmail.com>	2026-05-08 17:11:08 +02:00
Meier Lukas	2d15b3d407	chore(deps): update dependency zod to v4.4.3 (#5675 )	2026-05-08 17:10:22 +02:00
Manuel	44a2973b1a	revert(deps): downgrade pnpm to v10 (#5673 )	2026-05-08 16:03:12 +02:00
Manuel	00a055283e	fix(qbittorrent): support version 5.2 (#5672 )	2026-05-08 15:44:04 +02:00
Manuel	a474dcd961	chore: exclude renovate managed files from codeowners (#5676 )	2026-05-08 15:37:41 +02:00
homarr-update-contributors[bot]	69fe180968	chore: update contributors (#5674 ) Co-authored-by: Homarr Update Contributors <210161987+homarr-update-contributors[bot]@users.noreply.github.com>	2026-05-08 13:25:53 +00:00