Table of contents

• Installation
  • Requirements
  • Virtual environment
    • For Windows
    • For Linux
  • Launch
• Usage and examples
• Engines in details
  • Engines list
  • How to add an engine
• Integration with terminal

Installation

Requirements

• Python is required.
• Download the last release OR launch the following command

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

• Move into the folder of Binocle

cd binocle

Virtual environment

Even if it's optionnal, it is recommended to create a virutal environment.

For Windows

py -m venv venv
venv\Scripts\activate

For Linux

python3 -m venv venv
source venv/bin/activate

Launch

• To install Python dependencies, launch the following commands

pip install -r requirements.txt

• Launch Binocle

cd launcher
binocle

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
meta	Metacritic
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 with terminal

Binocle can be launched throught a terminal with the command binocle. The idea is to add Binocle 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.