Table of contents

• Quick start
  • Installation
  • Usage and examples
• Engines in details
  • Engines list
  • How to add an engine
• Integration
  • Terminal
  • AutoHotKey

Quick start

Installation

• Python must be installed on your device.
• Either, download the last release or launch the following command :

git clone https://github.com/ndeleforge/binocle.git

• Some dependancies are required, in Binocle's folder, launch the following command :

pip install -r requirements.txt

Usage and examples

Binocle has two ways of working :

• Using default engine search

binocle "hello it is a super research"

• Specify an engine search

binocle d "hello it is a super research"

Those two commands do exactly the same thing.
In the /config/config.json file, a default engine is defined. By default, it is Duckduckgo but you can change it to anything which exists as engine in the /config/engines.json file.

To summarize, if only one argument is used then the default engine will be used. However, to specify another search engine, the engine keyword must be used before the query search.

More examples :

• Search My Super Research on Duckduckgo :

binocle d "My Super Research"

• Search SomeYoutuber on Youtube :

binocle yt SomeYoutuber

There are also some optionnals arguments :

• -v or --version : show version
• -h or --help : show help
• -l or --list : show engines list

Engines in details

Engines list

Keyword	Search on
alt	Alternative To
b	Bing
ch	Chocolatey
d	Duckduckgo
e	Ecosia
g	Google
gi	Github
hltb	HowLongTo Beat
li	LinkedIn
mal	MyAnimeList
q	Qwant
re	Reddit
s	Startpage
so	StackOverflow
tw	Twitch
wi	Wikipedia
yt	Youtube

How to add an engine

An engine is composed of 3 mandatory values :

• name : must be a string and unique
• keyword : must be a string and unique
• url : must be a string and unique

Edit the /config/engines.json file and follow this template :

{
    "name": "My new engine",
    "keyword": "new",
    "url": "https://some.url"
}

Integration

Terminal

Binocle can be launched throught a terminal with the command binocle. The idea is to add Binocle's scripts folder in your PATH global variable.
It is doable for Windows with binocle.bat and Linux with binocle.sh which both are a shortcut for binocle.py.

AutoHotKey

Binocle can be launched with a keyboard shortcut.

Here is an example of what can be done with AHK :

; Call Binocle [CTRL + ALT + B]
^!B::
	gui, Add, Text, x10 y10 w180 h15, Enter your request :
	gui, Add, Edit, x10 y40 w180 h20 vUserInput
	gui, Add, Button, x20 y80 w60 h0 gStartBinocle Default Hidden, OK
	gui, +Border -SysMenu +Caption
	gui, Show, , 👓 Binocle
return

StartBinocle:
	gui, Submit, NoHide
	if (userInput != "") {
		run, python /path/to/Binocle %userInput%
	}
	gui, Destroy
return

If you want to use this macro, do not forget to replace the path for the Binocle Python file!

To explain, when you type on CTRL ALT and B at the same time, it will trigger the first macro and create a GUI with an input. You can then type your Binocle request and type on Enter, which will trigger the second macro.