Skip to content

README.md

Latest commit

 

History

History
157 lines (105 loc) · 8.76 KB

README.md

File metadata and controls

157 lines (105 loc) · 8.76 KB
Raw

degoog-cli

CLI tool for scaffolding degoog extensions and searching your instance from the terminal.


Install

curl -fsSL https://raw.githubusercontent.com/degoog-org/cli/main/install.sh | sh

The installer asks whether you want Docker or a native binary. Docker is the one to pick. It has no runtime dependencies, and a pull keeps it up to date. Native binaries exist for Linux x64/arm64 and macOS x64/arm64. On Windows, use Docker.

Once installed, run it from anywhere:

degoog-cli
Manual install for the nerds

Docker Compose

Grab the docker-compose.yml from this repo and run it from any directory:

curl -fsSL https://raw.githubusercontent.com/degoog-org/cli/main/docker-compose.yml -o docker-compose.yml
docker compose run --rm degoog-cli

The CLI creates extensions in whichever directory you run it from. Config persists at ~/.config/degoog on your host.

Native binary

Download the binary for your platform from releases, make it executable, and put it on your $PATH:

# Linux x64 example
curl -fsSL https://github.com/degoog-org/cli/releases/latest/download/degoog-cli-linux-x64 \
  -o /usr/local/bin/degoog-cli
chmod +x /usr/local/bin/degoog-cli

Available filenames: degoog-cli-linux-x64, degoog-cli-linux-arm64, degoog-cli-darwin-x64, degoog-cli-darwin-arm64.

Setup

Run login once to point the CLI at your instance and save your author details:

degoog-cli

Pick Login / Setup from the menu. The instance URL and API key unlock the search command.

Search

Select Search from the menu to search your degoog instance from the terminal. Each result shows its title, URL, snippet, and sources. Pick one to open it in your browser, or keep searching.

Search needs a configured instance URL.

Create an extension

Select Create extension from the menu and follow the prompts, or skip them with flags:

degoog-cli create --name my-engine --type engine --out ./extensions

The CLI asks for any flag you leave out, unless it runs headless (see below). The types are:

Type What it is
engine Custom search engine
transport Custom HTTP fetch strategy
autocomplete Search suggestions provider
favicon Favicon provider for search results
theme UI theme with CSS variables and optional template overrides
plugin-bang Bang command (!trigger query)
plugin-slot Panel injected into search results
plugin-tab Custom tab in search results
plugin-intercept Modifies queries before search
plugin-middleware Hooks into request flows
plugin-routes Custom HTTP endpoints

What gets generated

Every extension gets:

  • index.ts, the entry file, pre-filled with the contract for the type you picked. Favicon providers get index.js instead, to match the official store.
  • README.md, which shows as docs on the extension's settings page. Fill it in.
  • author.json, filled in from your login details.

Themes also get style.css with every CSS variable set to the degoog defaults for light and dark, plus a templates/logo.html example of overriding a template section.

The generated theme README also covers the script-free /nojs page. That page reuses your ordinary templates, and you override single files by dropping them in a nojs/ folder under the same filename, not through theme.json.

Plugin templates already include isClientExposed. Set it to true if your plugin makes the browser fetch external URLs directly, or false if everything goes through the server. Leave it unset and degoog settings shows a warning badge.

The commented settingsSchema in plugin and engine templates shows visibleWhen, which keeps a field hidden until another field holds a given value. Give equals an array to show one field for several dropdown options, so a single select can swap the rest of the form. notEquals shows a field while the value is anything else, and anyOf shows it when any one of several rules matches. Hidden required fields don't flag the extension as needing setup.

Engines ask whether the site puts an Anubis proof-of-work page in front of its results. Answer yes and the template sets challenges: ["anubis"], so degoog solves the page before your engine reads the response. Inside a store, the package.json entry also gets minDegoogVersion: "1.0.0", because degoog solves these pages from 1.0.0 onwards.

Transports ask whether they drive a real browser that gets through proof-of-work pages. Answer yes and the template sets handlesChallenges: true, so degoog leaves those pages to the engine.

Doctor checks both values. It fails on an unknown challenges kind or a handlesChallenges that isn't true or false, and warns when an engine with challenges has a minDegoogVersion below 1.0.0.

Doctor also warns about any image over 250 KB in an extension folder, screenshots included. Every degoog instance that adds your store downloads them, so the warning shows the image's size and dimensions plus a magick command that resizes it to 1600px and converts it to WebP. Degoog shows .webp screenshots like any other.

Running without prompts

Every command also runs without the interactive UI, for scripts, CI, or piping. The CLI goes headless when you pass -y / --yes, when stdin or stdout is not a terminal, or when CI or DEGOOG_HEADLESS=1 is set. Headless runs never prompt. They read flags, fall back to defaults, and exit 1 when a required value is missing or a check fails. The CLI drops colours when output is not a terminal, or with --no-color / NO_COLOR.

degoog-cli login --yes --instance-url https://search.example.com --api-key "$DEGOOG_API_KEY" --username "Jane Dev"
degoog-cli create --yes --name my-engine --type engine --challenges
degoog-cli create --yes --name my-theme --type theme --init-store --include css,home-logo
degoog-cli search --json --limit 5 "degoog extensions"
degoog-cli doctor ./my-store --fix --plugin-type command
Command Flags Headless defaults
create --name, --type, --out, --init-store, --challenges, --handles-challenges, --include <parts|all> --name and --type are required. Output goes to the detected store category, otherwise .
search <query>, --json, --limit <n> Query is required. --json always skips the result browser
login --instance-url (or DEGOOG_INSTANCE_URL), --api-key (or DEGOOG_API_KEY), --username, --website Only the values you pass are changed
doctor [path], --fix, --plugin-type <command|slot|interceptor|search-result-tab> Path defaults to the current directory. Orphan folders are only registered with --fix

Boolean flags accept --flag=false. Themes created headless without --include get css only. Orphan plugin folders are skipped unless --plugin-type is given, since doctor cannot guess their type. Run degoog-cli --help for the full list.

Docker Compose

If you'd rather use compose than the wrapper script:

docker compose run --rm degoog-cli

Extensions land in your current directory. Config persists at ~/.config/degoog on your host.

Dev (building from source)

Requires Bun.

bun install
bun run dev        # run without building
bun run build      # produces binaries in dist/ for all platforms