### Native Installation and Launch of Degoog

Source: https://context7.com/fccview/degoog/llms.txt

Install Degoog from source using Git and Bun. This method involves cloning the repository, installing dependencies, building the project, and starting the server.

```bash
git clone https://github.com/fccview/degoog.git
cd degoog
bun install
bun run build
bun run start
# Server running on http://localhost:4444
```

--------------------------------

### Native Installation and Run

Source: https://github.com/fccview/degoog/blob/main/README.md

Steps to clone the repository, install dependencies using bun, build, and start the degoog application natively.

```bash
git clone https://github.com/fccview/degoog.git
cd degoog
bun install
bun run build
bun run start
```

--------------------------------

### Example of Using an Alias

Source: https://github.com/fccview/degoog/blob/main/docs/aliases.html

An example demonstrating how to use a custom alias to execute a command. For instance, typing `!g linux kernel` searches Google for "linux kernel".

```text
!g linux kernel
```

--------------------------------

### Minimal Plugin Example (index.js)

Source: https://github.com/fccview/degoog/blob/main/docs/plugins.html

A basic plugin structure for a 'greeting' command. It initializes with a template and executes to replace a placeholder with a provided name.

```javascript
let template = "";

export default {
  name: "Greeting",
  description: "Say hello",
  trigger: "hello",
  init(ctx) { template = ctx.template; },
  async execute(args) {
    const name = args.trim() || "world";
    const html = template.replace("{{name}}", name);
    return { title: "Hello", html };
  },
};
```

--------------------------------

### Autocomplete Suggestions with curl

Source: https://context7.com/fccview/degoog/llms.txt

Get autocomplete suggestions from multiple search engines using the `/api/suggest` endpoint. This example queries for 'open sou'.

```bash
curl "http://localhost:4444/api/suggest?q=open+sou"
```

--------------------------------

### GraphQL Engine Example

Source: https://github.com/fccview/degoog/blob/main/docs/engines.html

Demonstrates how to implement a GraphQL engine using POST requests within `executeSearch`. It utilizes the provided `context.fetch` for HTTP calls and constructs a GraphQL query.

```javascript
async executeSearch(query, page = 1, _timeFilter, context) {
  const doFetch = context?.fetch ?? fetch;
  const response = await doFetch("https://graphql.example.com", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: MY_QUERY, variables: { search: query, page } }),
  });
  const data = await response.json();
  // parse and return array of { title, url, snippet, source }
}
```

--------------------------------

### Degoog Bang Command Examples

Source: https://context7.com/fccview/degoog/llms.txt

Illustrates built-in and custom bang command shortcuts for various search engines. Aliases defined in `data/aliases.json` can be used for further customization.

```bash
# Built-in engine bang shortcuts:
# !g <query>     → search only Google
# !b <query>     → search only Bing
# !ddg <query>   → search only DuckDuckGo
# !brave <query> → search only Brave Search
# !w <query>     → search only Wikipedia
# !r <query>     → search only Reddit

# Custom engine shortcut (defined in engine file):
# !eco <query>   → search only Ecosia (bangShortcut: "eco")

# With aliases above:
# !jelly <query> → same as !jellyfin <query>
```

--------------------------------

### Example package.json for a Store Repository

Source: https://github.com/fccview/degoog/blob/main/docs/store.html

This JSON structure is required at the root of your repository to list all items available in the Degoog Store. Ensure paths match actual folder locations within the repo.

```json
{
  "name": "my-degoog-repo",
  "description": "Short description of your collection",
  "author": "YourName",
  "plugins": [
    {
      "path": "plugins/my-plugin",
      "name": "My Plugin",
      "description": "What it does",
      "version": "1.0.0",
      "type": "command"
    }
  ],
  "themes": [
    {
      "path": "themes/my-theme",
      "name": "My Theme",
      "description": "Short description",
      "version": "1.0.0"
    }
  ],
  "engines": [],
  "transports": [],
  "repo-image": "logo.png"
}
```

--------------------------------

### GET /opensearch.xml

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

Provides an OpenSearch descriptor file, allowing browsers to install Degoog as a search engine.

```APIDOC
## GET /opensearch.xml

### Description
OpenSearch descriptor — lets browsers install Degoog as a search engine.

### Method
GET

### Endpoint
/opensearch.xml

### Response
#### Success Response (200)
- (XML) - The OpenSearch descriptor XML file.
```

--------------------------------

### Private Helper Function Example

Source: https://github.com/fccview/degoog/blob/main/CONTRIBUTING.md

Prepend internal or private helper functions with an underscore (_).

```javascript
const _parseQuery = (query) => {
  // ...
}
```

--------------------------------

### Inline Docker Run Command

Source: https://github.com/fccview/degoog/blob/main/README.md

Starts degoog as a detached Docker container, mapping ports and volumes, with a restart policy.

```bash
docker run -d --name degoog -p 4444:4444 -v ./data:/app/data --restart unless-stopped ghcr.io/fccview/degoog:latest
```

--------------------------------

### Arrow Function Example

Source: https://github.com/fccview/degoog/blob/main/CONTRIBUTING.md

Use arrow functions for functions that return a value. This promotes concise syntax.

```javascript
const getX = () => value
```

--------------------------------

### Perform a web search using POST

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

This endpoint is similar to the GET version but accepts a JSON body. It is recommended for scenarios requiring a long list of search engines.

```bash
curl -X POST http://localhost:4444/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rust lifetimes",
    "type": "web",
    "page": 1,
    "lang": "en",
    "engines": ["google", "duckduckgo"]
  }'
```

--------------------------------

### GET /api/suggest

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

Provides autocomplete suggestions merged from Google and DuckDuckGo.

```APIDOC
## GET /api/suggest

### Description
Autocomplete suggestions merged from Google and DuckDuckGo.

### Method
GET

### Endpoint
/api/suggest

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query for which to get suggestions.

### Response
#### Success Response (200)
- (array) - An array of suggestion strings.

### Response Example
```json
["suggestion1", "suggestion2"]
```
```

--------------------------------

### Example author.json for an Item

Source: https://github.com/fccview/degoog/blob/main/docs/store.html

Optional author.json file to override the repository author for a specific plugin, theme, engine, or transport. This allows for individual attribution within a collection.

```json
{
  "name": "Author Name",
  "url": "https://github.com/username",
  "avatar": "https://example.com/avatar.png"
}
```

--------------------------------

### Perform a web search using GET

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

Use this endpoint to perform a metasearch and retrieve merged, scored results. You can specify the search query, type, page number, time range, and language.

```bash
curl "http://localhost:4444/api/search?q=rust+lifetimes"
```

--------------------------------

### CSS Variable Usage Example

Source: https://github.com/fccview/degoog/blob/main/CONTRIBUTING.md

Utilize SCSS/CSS variables for styling to ensure theme and dark/light mode compatibility. Reuse existing app classes where possible.

```css
$primary or var(--text-primary)
```

--------------------------------

### OpenSearch descriptor for browser integration

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

This endpoint provides the OpenSearch descriptor, allowing browsers to install Degoog as a search engine.

```xml
GET /opensearch.xml
```

--------------------------------

### Trigger At-a-glance Slot with JSON Body (POST)

Source: https://context7.com/fccview/degoog/llms.txt

Fetch the at-a-glance slot panel separately using the `/api/slots/glance` endpoint. This is typically loaded asynchronously after the main results. This example uses 'Interstellar' as the query and provides a sample result.

```bash
curl -X POST http://localhost:4444/api/slots/glance \
  -H "Content-Type: application/json" \
  -d '{"query": "Interstellar", "results": [{"title":"...","url":"...","snippet":"...","source":"google","score":90,"sources":["google"]}]}'
```

--------------------------------

### Settings Schema Field Example

Source: https://github.com/fccview/degoog/blob/main/docs/plugins.html

Illustrates the structure for defining a single field within a plugin's `settingsSchema`. Supports various input types and validation.

```javascript
{
  key: "api_key",
  label: "API Key",
  type: "password",
  required: true,
  placeholder: "Enter your API key",
  description: "Your secret API key for authentication.",
  secret: true
}
```

--------------------------------

### Forcing Locale for Development

Source: https://github.com/fccview/degoog/blob/main/docs/translations.html

Start the development server with a specific locale forced using the `DEGOOG_I18N` environment variable to verify translations.

```bash
DEGOOG_I18N=it-IT npm run dev
```

--------------------------------

### Store Repository Package Manifest

Source: https://context7.com/fccview/degoog/llms.txt

Manifest file for a store repository, defining plugins, themes, and engines that can be installed. This JSON file lists available extensions.

```json
// my-degoog-repo/package.json
{
  "name": "my-degoog-repo",
  "description": "My collection of degoog extensions",
  "author": "YourName",
  "repo-image": "logo.png",
  "plugins": [
    {
      "path": "plugins/weather",
      "name": "Weather",
      "description": "Show current weather via !weather city",
      "version": "1.2.0",
      "type": "command"
    },
    {
      "path": "plugins/tmdb-slot",
      "name": "TMDb Slot",
      "description": "Shows movie/TV info above results",
      "version": "0.9.0",
      "type": "slot"
    }
  ],
  "themes": [
    {
      "path": "themes/dark-minimal",
      "name": "Dark Minimal",
      "description": "Clean dark theme",
      "version": "1.0.0"
    }
  ],
  "engines": [
    {
      "path": "engines/ecosia",
      "name": "Ecosia",
      "description": "Web search via Ecosia",
      "version": "1.0.0"
    }
  ],
  "transports": []
}
```

--------------------------------

### Advanced Web Search with curl

Source: https://context7.com/fccview/degoog/llms.txt

Perform an advanced web search with parameters for image type, pagination, time range, and language. This example searches for 'mountains'.

```bash
curl "http://localhost:4444/api/search?q=mountains&type=images&page=2&time=week&lang=de"
```

--------------------------------

### I'm Feeling Lucky Redirect with curl

Source: https://context7.com/fccview/degoog/llms.txt

Perform a web search and redirect to the first result's URL using the `/api/lucky` endpoint. This example searches for 'bun runtime docs'. Use the `-L` flag to follow redirects.

```bash
curl -L "http://localhost:4444/api/lucky?q=bun+runtime+docs"
```

--------------------------------

### Manually Verify Open WebUI Integration with Curl

Source: https://context7.com/fccview/degoog/llms.txt

Use curl to send a search query to the Degoog API endpoint and verify the integration with Open WebUI. The response format can be specified, for example, as JSON.

```bash
# Verify the integration manually
curl "http://localhost:4444/api/search?q=latest+AI+models&format=json"
```

--------------------------------

### Define Plugin HTTP Routes

Source: https://context7.com/fccview/degoog/llms.txt

Exposes custom HTTP endpoints for a plugin under `/api/plugin/<folderName>/`. Includes a GET endpoint for status and a POST endpoint for actions.

```javascript
// data/plugins/my-plugin/index.js
export const routes = [
  {
    method: "get",
    path: "/status",
    handler(req) {
      return Response.json({ ok: true, uptime: process.uptime() });
    },
  },
  {
    method: "post",
    path: "/action",
    async handler(req) {
      const body = await req.json();
      // process body.data
      return Response.json({ received: body.data });
    },
  },
];

// Client-side script.js can call:
// fetch("/api/plugin/my-plugin/status").then(r => r.json())
// fetch("/api/plugin/my-plugin/action", { method:"POST", body: JSON.stringify({data:"hello"}) })

```

--------------------------------

### Trigger Slot Plugins with JSON Body (POST)

Source: https://context7.com/fccview/degoog/llms.txt

Trigger slot plugins to fetch rendered HTML panels for various sections (above-results, below-results, sidebar, knowledge-panel) using the `/api/slots` endpoint. This example uses 'Interstellar' as the query and provides an empty results array.

```bash
curl -X POST http://localhost:4444/api/slots \
  -H "Content-Type: application/json" \
  -d '{"query": "Interstellar", "results": []}'
```

--------------------------------

### Execute Search with Ecosia Engine

Source: https://context7.com/fccview/degoog/llms.txt

Implements the `executeSearch` method for the Ecosia search engine. It handles query parameters, time filters, and parses HTML results using Cheerio. Requires `cheerio` to be installed.

```javascript
// data/engines/ecosia/index.js
import * as cheerio from "cheerio";

export const outgoingHosts = ["www.ecosia.org"];

export default class EcosiaEngine {
  name = "Ecosia";
  bangShortcut = "eco";

  settingsSchema = [
    {
      key: "safeSearch",
      label: "Safe Search",
      type: "select",
      options: ["off", "moderate", "strict"],
      default: "moderate",
    },
  ];

  safeSearch = "moderate";
  configure(settings) {
    if (settings.safeSearch) this.safeSearch = settings.safeSearch;
  }

  async executeSearch(query, page = 1, timeFilter, context) {
    const doFetch = context?.fetch ?? fetch;
    const acceptLang = context?.buildAcceptLanguage?.() ?? "en,en-US;q=0.9";

    const params = new URLSearchParams({
      q: query,
      p: String(page - 1),
      safesearch: this.safeSearch,
    });

    if (timeFilter === "day") params.set("when", "24h");
    else if (timeFilter === "week") params.set("when", "7d");
    else if (timeFilter === "custom" && context?.dateFrom) {
      params.set("from", context.dateFrom);
      if (context.dateTo) params.set("to", context.dateTo);
    }

    const res = await doFetch(`https://www.ecosia.org/search?${params}`, {
      headers: { "Accept-Language": acceptLang, "User-Agent": "Mozilla/5.0" },
    });
    if (!res.ok) return [];

    const html = await res.text();
    const $ = cheerio.load(html);
    const results = [];

    $(".result__body").each((_, el) => {
      const title = $(el).find(".result__title").text().trim();
      const url = $(el).find(".result__link").attr("href") ?? "";
      const snippet = $(el).find(".result__description").text().trim();
      if (title && url) results.push({ title, url, snippet, source: "ecosia" });
    });

    return results;
  }
}
```

--------------------------------

### Prepare Data Directory and Launch Degoog via Docker

Source: https://context7.com/fccview/degoog/llms.txt

Prepare the local data directory for Degoog and launch the Docker container. Access the service via the specified localhost port.

```bash
# Prepare data directory and launch
mkdir -p ./data
sudo chown -R 1000:1000 ./data
docker compose up -d
# Access at http://localhost:4444
```

--------------------------------

### GET /api/lucky

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

Performs a web search and redirects to the URL of the first result.

```APIDOC
## GET /api/lucky

### Description
Runs a web search and `302`-redirects to the first result's URL.

### Method
GET

### Endpoint
/api/lucky

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query.

### Response
#### Redirect Response
- (302 Redirect) - Redirects to the URL of the first search result.
```

--------------------------------

### Plugin Initialization Context

Source: https://github.com/fccview/degoog/blob/main/docs/plugins.html

The `init(ctx)` function receives a context object with properties like `template`, `dir`, and `readFile`. Use `ctx.readFile` to access other files within the plugin folder.

```javascript
init(ctx) {
  // ctx.template — contents of template.html (or "")
  // ctx.dir      — absolute path to the plugin folder
  // ctx.readFile — async function to read any file from your plugin folder
}
```

--------------------------------

### Initialize Theme Settings

Source: https://github.com/fccview/degoog/blob/main/src/public/settings-public.html

Sets the theme for the application based on local storage or system preferences. It applies a 'data-theme' attribute to the document element.

```javascript
(function () { var t = localStorage.getItem("theme"); var r = document.documentElement; if (t === "light") r.setAttribute("data-theme", "light"); else if (t === "dark") r.setAttribute("data-theme", "dark"); else { var m = window.matchMedia("(prefers-color-scheme: dark)"); r.setAttribute("data-theme", m.matches ? "dark" : "light"); } })();
```

--------------------------------

### Regular Function Declaration Example

Source: https://github.com/fccview/degoog/blob/main/CONTRIBUTING.md

Use regular function declarations for functions that are side-effect only and do not return a value.

```javascript
function processData(data) {
  // side-effect only
}
```

--------------------------------

### Prepare Data Directory

Source: https://github.com/fccview/degoog/blob/main/README.md

Ensures the data directory exists and has the correct ownership before running the application.

```bash
mkdir -p ./data
sudo chown -R 1000:1000 ./data
```

--------------------------------

### GET /api/suggest — Autocomplete suggestions

Source: https://context7.com/fccview/degoog/llms.txt

Retrieves merged autocomplete suggestions from configured search engines.

```APIDOC
## GET /api/suggest — Autocomplete suggestions

### Description
Returns merged autocomplete suggestions from Google and DuckDuckGo as a `string[]`.

### Method
GET

### Endpoint
/api/suggest

### Parameters
#### Query Parameters
- **q** (string) - Required - The prefix for which to get suggestions.

### Response
#### Success Response (200)
- **string[]** - An array of autocomplete suggestion strings.

### Request Example
```bash
curl "http://localhost:4444/api/suggest?q=open+sou"
```

### Response Example
```json
["open source", "open source software", "open source licenses", ...]
```
```

--------------------------------

### Get autocomplete suggestions

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

Retrieve autocomplete suggestions merged from Google and DuckDuckGo by providing a query parameter.

```bash
GET /api/suggest?q=...
```

--------------------------------

### Handle Search Parameters and Fetching

Source: https://github.com/fccview/degoog/blob/main/docs/engines.html

Construct URL search parameters including language and time filters, then perform a fetch request with custom headers. Ensure to use context.fetch for proxy compatibility.

```javascript
if (lang) params.set("lang", lang);

    if (timeFilter === "day") params.set("when", "24h");
    else if (timeFilter === "week") params.set("when", "7d");
    else if (timeFilter === "custom" && context?.dateFrom) {
      params.set("from", context.dateFrom);
      if (context.dateTo) params.set("to", context.dateTo);
    }

    const res = await doFetch(`https://example.com/search?${params}`, {
      headers: { "Accept-Language": acceptLang },
    });
    // parse and return array of { title, url, snippet, source }
```

--------------------------------

### Basic theme.json Configuration

Source: https://github.com/fccview/degoog/blob/main/docs/themes.html

A minimal `theme.json` file requires at least a `name`. You can also specify a `css` file and map custom `templates`.

```json
{
  "name": "My Theme",
  "css": "style.css",
  "templates": {
    "result": "templates/result.html"
  }
}
```

--------------------------------

### GET /api/search/stream

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

A Server-Sent Events (SSE) variant of the search API. It emits events as results become available.

```APIDOC
## GET /api/search/stream

### Description
Server-Sent Events variant. Same query parameters as `GET /api/search`. Emits:

*   `engine-result` — fired as each engine returns. The `results` field is the running merged list, so a lazy consumer can just keep the last one.
*   `done` — final event with `totalTime`, `engineTimings`, `relatedSearches`.

### Method
GET

### Endpoint
/api/search/stream

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query.
- **type** (string) - Optional - `web` (default) | `images` | `videos` | `news`.
- **page** (integer) - Optional - 1-based page number. Clamped to `1..10`.
- **time** (string) - Optional - `any` | `hour` | `day` | `week` | `month` | `year` | `custom`. For `custom`, pass `dateFrom` / `dateTo` (`YYYY-MM-DD`).
- **lang** (string) - Optional - ISO 639-1 code. Overrides `DEGOOG_DEFAULT_SEARCH_LANGUAGE` for this request.

### Request Example
```bash
curl -N "http://localhost:4444/api/search/stream?q=hello"
```
```

--------------------------------

### Initialize Theme Settings

Source: https://github.com/fccview/degoog/blob/main/src/public/settings-gate.html

Sets the data-theme attribute on the document element based on local storage, IndexedDB, or system preferences.

```javascript
(function () { var r = document.documentElement; var t = localStorage.getItem("theme"); if (t === "light") r.setAttribute("data-theme", "light"); else if (t === "dark") r.setAttribute("data-theme", "dark"); else { var m = window.matchMedia("(prefers-color-scheme: dark)"); r.setAttribute("data-theme", m.matches ? "dark" : "light"); } try { var req = indexedDB.open("degoog", 2); req.onsuccess = function () { try { var db = req.result; if (!db.objectStoreNames.contains("settings")) return; var tx = db.transaction("settings", "readonly"); var store = tx.objectStore("settings"); var get = store.get("theme"); get.onsuccess = function () { var v = get.result; if (v === "light") r.setAttribute("data-theme", "light"); else if (v === "dark") r.setAttribute("data-theme", "dark"); else { var m2 = window.matchMedia("(prefers-color-scheme: dark)"); r.setAttribute("data-theme", m2.matches ? "dark" : "light"); } }; } catch (e) {} }; } catch (e) {} })();
```

--------------------------------

### Minimal Degoog Transport Implementation

Source: https://github.com/fccview/degoog/blob/main/docs/transports.html

A basic transport class demonstrating how to define settings, configure the transport, check availability, and implement the fetch method. Ensure `apiUrl` is provided in settings for this transport to be available.

```javascript
export default class MyTransport {
  name = "my-transport";
  displayName = "My Transport";
  description = "Example custom transport.";

  settingsSchema = [
    {
      key: "apiUrl",
      label: "API URL",
      type: "url",
      required: true,
      placeholder: "https://my-service.example.com",
    },
  ];

  _apiUrl = "";

  configure(settings) {
    this._apiUrl = (settings.apiUrl || "").trim();
  }

  available() {
    return this._apiUrl.length > 0;
  }

  async fetch(url, options, context) {
    const doFetch = context.fetch;

    const res = await doFetch(this._apiUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ url, timeout: 10000 }),
      signal: options.signal,
    });

    if (!res.ok) return new Response("", { status: res.status });
    const data = await res.json();
    return new Response(data.html ?? "", {
      status: data.status ?? 200,
      headers: { "Content-Type": "text/html" },
    });
  }
}
```

--------------------------------

### GET /api/search

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

Runs a metasearch and returns merged, scored results. Supports various query parameters for filtering and pagination.

```APIDOC
## GET /api/search

### Description
Run a metasearch and return merged, scored results.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query.
- **type** (string) - Optional - `web` (default) | `images` | `videos` | `news`.
- **page** (integer) - Optional - 1-based page number. Clamped to `1..10`.
- **time** (string) - Optional - `any` | `hour` | `day` | `week` | `month` | `year` | `custom`. For `custom`, pass `dateFrom` / `dateTo` (`YYYY-MM-DD`).
- **lang** (string) - Optional - ISO 639-1 code. Overrides `DEGOOG_DEFAULT_SEARCH_LANGUAGE` for this request.

### Request Example
```bash
curl "http://localhost:4444/api/search?q=rust+lifetimes"
```

### Response
#### Success Response (200)
- **results** (array) - Array of search result objects.
  - **title** (string) - The title of the search result.
  - **url** (string) - The URL of the search result.
  - **snippet** (string) - A short description or snippet of the search result.
  - **source** (string) - The search engine that provided the result.
  - **score** (integer) - The relevance score of the result.
  - **sources** (array) - List of sources the result came from.
- **query** (string) - The original search query.
- **totalTime** (integer) - Total time taken for the search in milliseconds.
- **type** (string) - The type of search performed.
- **engineTimings** (array) - Timing information for each search engine used.
  - **name** (string) - The name of the search engine.
  - **time** (integer) - Time taken by the engine in milliseconds.
  - **resultCount** (integer) - Number of results returned by the engine.
- **relatedSearches** (array) - List of related search queries.

#### Response Example
```json
{
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "snippet": "...",
      "source": "google",
      "score": 92,
      "sources": ["google", "duckduckgo"]
    }
  ],
  "query": "rust lifetimes",
  "totalTime": 812,
  "type": "web",
  "engineTimings": [{ "name": "Google", "time": 540, "resultCount": 10 }],
  "relatedSearches": ["rust lifetime elision", "..."]
}
```
```

--------------------------------

### Plugin Stylesheet (style.css)

Source: https://github.com/fccview/degoog/blob/main/docs/plugins.html

CSS for the greeting plugin. Uses CSS variables for theming.

```css
/* use `var(--text-primary)` etc.; see [Styling](styling.html). */
```

--------------------------------

### GET /api/search-tabs — List custom search tabs

Source: https://context7.com/fccview/degoog/llms.txt

Retrieves a list of all registered custom search result tab plugins.

```APIDOC
## GET /api/search-tabs — List custom search tabs

### Description
Returns all registered search result tab plugins.

### Method
GET

### Endpoint
/api/search-tabs

### Response
#### Success Response (200)
- **array** - List of custom search tab objects.
  - **id** (string) - Unique identifier for the tab.
  - **name** (string) - Display name for the tab.
  - **icon** (string) - URL or identifier for the tab's icon.

### Request Example
```bash
curl "http://localhost:4444/api/search-tabs"
```

### Response Example
```json
[ { "id": "weeb", "name": "Anime", "icon": "..." } ]
```
```

--------------------------------

### Configure Degoog for Open WebUI

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

Instructions on how to integrate Degoog with Open WebUI by setting the web search engine to 'searxng' and providing the Degoog API search URL.

```text
1. Open WebUI → **Admin Panel**.
2. Go to **Settings**.
3. Select **Web Search** and enable it.
4. Set **Web Search Engine** to `searxng`.
5. Set **SearxNG Query URL** to your Degoog instance URL + `/api/search`, e.g. `http://127.0.0.1:4444/api/search`.

Replace `http://127.0.0.1:4444` with your actual Degoog address.
```

--------------------------------

### GET /api/lucky — I'm Feeling Lucky redirect

Source: https://context7.com/fccview/degoog/llms.txt

Performs a web search and redirects the user to the URL of the first result.

```APIDOC
## GET /api/lucky — I'm Feeling Lucky redirect

### Description
Runs a web search and `302`-redirects to the first result's URL.

### Method
GET

### Endpoint
/api/lucky

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query.

### Response
#### Redirect (302)
- Redirects to the URL of the first search result.

### Request Example
```bash
curl -L "http://localhost:4444/api/lucky?q=bun+runtime+docs"
```
```

--------------------------------

### POST /api/search

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

Same functionality as GET /api/search but accepts parameters via a JSON request body. Useful for longer engine lists.

```APIDOC
## POST /api/search

### Description
Same as the GET form, with a JSON body. Use this when you need a long engine list.

### Method
POST

### Endpoint
/api/search

### Parameters
#### Request Body
- **query** (string) - Required - Search query.
- **type** (string) - Optional - `web` (default) | `images` | `videos` | `news`.
- **page** (integer) - Optional - 1-based page number.
- **lang** (string) - Optional - ISO 639-1 code.
- **engines** (array) - Optional - List of search engines to use.

### Request Example
```bash
curl -X POST http://localhost:4444/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rust lifetimes",
    "type": "web",
    "page": 1,
    "lang": "en",
    "engines": ["google", "duckduckgo"]
  }'
```
```

--------------------------------

### Podman Run Command

Source: https://github.com/fccview/degoog/blob/main/README.md

Launches degoog as a detached container using Podman, specifying port mapping, volume, and restart policy.

```bash
podman run -d --name degoog -p 4444:4444 -v ./data:/app/data --security-opt label=disable --restart unless-stopped ghcr.io/fccview/degoog:latest
```

--------------------------------

### Open WebUI Integration Configuration for Degoog

Source: https://context7.com/fccview/degoog/llms.txt

Configure Open WebUI to use Degoog as a SearXNG-compatible web search backend. Set the engine to 'searxng' and provide the Degoog API endpoint URL.

```text
1. Open WebUI → Admin Panel → Settings → Web Search
2. Enable Web Search
3. Set Web Search Engine to: searxng
4. Set SearxNG Query URL to: http://<your-degoog-host>:4444/api/search
```

--------------------------------

### Podman Quadlet Container File

Source: https://github.com/fccview/degoog/blob/main/README.md

Configuration file for Podman's Quadlet to manage degoog as a systemd service, including environment variables and volume mapping.

```yaml
[Unit]
Description=Degoog selfhosted search aggregator
Wants=network-online.target
After=network-online.target

[Container]
Image=ghcr.io/fccview/degoog:latest
AutoUpdate=registry
ContainerName=degoog
Environment=TZ=<Country/City>
Environment=PUID=1000
Environment=PGID=1000
# Environment=DEGOOG_PUBLIC_INSTANCE=true # Add if public
UIDMap=+%U:@%U
Volume=<Path to config>:/app/data:Z
PublishPort=4444:4444
Network=degoog

[Service]
Restart=always

[Install]
WantedBy=default.target
```

--------------------------------

### Fetch OpenSearch Descriptor with curl

Source: https://context7.com/fccview/degoog/llms.txt

Fetch the OpenSearch descriptor file using the `/opensearch.xml` endpoint. This allows browsers to register degoog as a native search engine.

```bash
curl "http://localhost:4444/opensearch.xml"
```

--------------------------------

### Custom Date Range Search with curl

Source: https://context7.com/fccview/degoog/llms.txt

Perform a web search with a custom date range using the `dateFrom` and `dateTo` parameters. This example searches for 'linux kernel'.

```bash
curl "http://localhost:4444/api/search?q=linux+kernel&time=custom&dateFrom=2024-01-01&dateTo=2024-06-30"
```

--------------------------------

### Basic Engine Implementation

Source: https://github.com/fccview/degoog/blob/main/docs/engines.html

A minimal implementation of a custom search engine class. It defines the `name` property and an `executeSearch` method that handles query parameters and language context.

```javascript
export default class MyEngine {
  name = "My Search";

  async executeSearch(query, page = 1, timeFilter, context) {
    const lang = context?.lang;
    const acceptLang = context?.buildAcceptLanguage?.() ?? "en,en-US;q=0.9";
    const doFetch = context?.fetch ?? fetch;

    const params = new URLSearchParams({ q: query });

```

--------------------------------

### Copying English Locale Files

Source: https://github.com/fccview/degoog/blob/main/docs/translations.html

This script demonstrates how to copy the default English locale files to a new language directory and for built-in commands.

```bash
LANG=it-IT
SLANG=it

cp src/locales/en-US.json src/locales/$LANG.json
cp src/public/themes/degoog-theme/locales/en-US.json \
   src/public/themes/degoog-theme/locales/$LANG.json

for cmd in help ip ai-summary speedtest uuid; do
  cp src/server/extensions/commands/builtins/$cmd/locales/en.json \
     src/server/extensions/commands/builtins/$cmd/locales/$SLANG.json
done
```

--------------------------------

### Define Custom Aliases in JSON

Source: https://github.com/fccview/degoog/blob/main/docs/aliases.html

Create a JSON file (e.g., data/aliases.json) to define your custom command aliases. Each key is the alias and its value is the target command.

```json
{
  "jelly": "jellyfin",
  "search": "meili",
  "id": "uuid"
}
```

--------------------------------

### Perform a 'lucky' search and redirect

Source: https://github.com/fccview/degoog/blob/main/docs/api.html

This endpoint performs a web search and redirects the user to the URL of the first result.

```bash
GET /api/lucky?q=...
```

--------------------------------

### GET /api/search — Metasearch query

Source: https://context7.com/fccview/degoog/llms.txt

Runs a search across all enabled engines, merges and deduplicates results, and returns them ranked by score. Supports various parameters for filtering and pagination.

```APIDOC
## GET /api/search — Metasearch query

### Description
Runs a search across all enabled engines, merges and deduplicates results, and returns them ranked by score.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query.
- **type** (string) - Optional - The type of search (e.g., 'images').
- **page** (integer) - Optional - The page number for results.
- **time** (string) - Optional - Time filter for results (e.g., 'week', 'custom').
- **lang** (string) - Optional - Language code for the search (e.g., 'de').
- **dateFrom** (string) - Optional - Start date for custom time range (YYYY-MM-DD).
- **dateTo** (string) - Optional - End date for custom time range (YYYY-MM-DD).

### Response
#### Success Response (200)
- **results** (array) - Array of search result objects.
  - **title** (string) - The title of the search result.
  - **url** (string) - The URL of the search result.
  - **snippet** (string) - A brief description or snippet from the result.
  - **source** (string) - The search engine that provided the result.
  - **score** (integer) - The relevance score of the result.
  - **sources** (array) - List of search engines that returned this result.
- **query** (string) - The original search query.
- **totalTime** (integer) - Total time in milliseconds to complete the search.
- **type** (string) - The type of search performed.
- **engineTimings** (array) - Details on time spent and results from each engine.
- **relatedSearches** (array) - List of related search queries.

### Request Example
```bash
curl "http://localhost:4444/api/search?q=rust+lifetimes"
```

### Response Example
```json
{
  "results": [
    {
      "title": "Understanding Rust Lifetimes",
      "url": "https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html",
      "snippet": "Every reference in Rust has a lifetime...",
      "source": "google",
      "score": 92,
      "sources": ["google", "duckduckgo"]
    }
  ],
  "query": "rust lifetimes",
  "totalTime": 812,
  "type": "web",
  "engineTimings": [
    { "name": "Google", "time": 540, "resultCount": 10 },
    { "name": "DuckDuckGo", "time": 310, "resultCount": 8 }
  ],
  "relatedSearches": ["rust lifetime elision", "rust borrow checker"]
}
```
```

--------------------------------

### Plugin Folder Structure

Source: https://github.com/fccview/degoog/blob/main/docs/plugins.html

Defines the standard file organization for a Degoog plugin. The entry point must be named index.js, index.ts, index.mjs, or index.cjs.

```plaintext
data/plugins/
  my-plugin/
    index.js        # required — entry point
    template.html   # optional
    style.css       # optional
    script.js       # optional
    card.html       # optional — read via ctx.readFile()
    author.json     # optional — for Store display
```

--------------------------------

### Stream Search Results with curl

Source: https://context7.com/fccview/degoog/llms.txt

Stream search results as Server-Sent Events (SSE) using the `/api/search/stream` endpoint. This allows for lazy consumption of results as they become available. This example searches for 'open source AI'.

```bash
curl -N "http://localhost:4444/api/search/stream?q=open+source+AI"
```

--------------------------------

### Plugin Template (template.html)

Source: https://github.com/fccview/degoog/blob/main/docs/plugins.html

HTML template for the greeting plugin, displaying a personalized greeting.

```html
<div class="command-result greeting">
  <h3 class="greeting-title">Hello, {{name}}!</h3>
</div>
```