Say 'Hello' to new CLI

Brand new Ferret CLI

April 22, 2021 by Tim Voronov

Hello fellas,

We are happy to announce that we finally have a brand new Ferret CLI!

As the project grows, it became clear that we need to separate Ferret Runtime and CLI, to let the projects evolve on their own.

The separation allowed us to review what we need from CLI and rebuild it from the ground up.

Thus, let’s dive in and see what’s in there.

Get started

First of all, we need to install it:

$ curl | sudo sh

If you want to install it to a particular folder set it to LOCATION environment variable:

$ curl | LOCATION=my-dir sh

What’s broken

Let’s start with some breaking changes.

Fortunately, there is only one breaking change: now if you want to execute a script or enter to REPL, you need to call exec command:

$ ferret exec
Welcome to Ferret REPL 0.14.1

Please use `exit` or `Ctrl-D` to exit this program.
$ ferret exec my-script.fql

What’s new

Remote runtime

Alternative to built-in runtime, you can tell CLI to execute a given script using the remote one!

$ ferret exec --runtime my-script.fql
The remote runtime must support the same request contract as Ferret Worker does.

Auto-browser launch

With new CLI, you can easily run your script with automatically open local browser:

$ ferret exec --browser-open my-script.fql

--browser-open will inform CLI to find locally installed Chrome or Chromium and open it before execution.

In case if you don’t want your browser to be visible during execution, you can pass --browser-headless flag to open it in the headless mode:

$ ferret exec --browser-headless my-script.fql
At this moment, CLI does not support browser installation, thus Chrome/Chromium must be installed on your machine before using these flags.

Browser management

Also, you can briefly manage your local browser by openning and closing it.

$ ferret browser open
$ ferret browser open -d

-d flag indicates that the browser needs to be open in the background i.e. the proccess will exit once the browser is open and ready to be used and return the process id.

$ ferret browser close process-id
$ ferret browser close

close without a given process id will try to find early opened browser with local debugging options.

In the future, we will add more options for browser management.


New CLI allows you to store overriden default flag values, by using configuration files.

The list of supported configuration keys you can get by using the following command:

$ ferret config ls

log-level: info
runtime: <nil>
browser-cookies: <nil>
browser-address: <nil>
browser-open: <nil>
browser-headless: <nil>
proxy: <nil>
user-agent: <nil>

For example, let’s set browser-open to true so, every time we run our script, the browser would be opened:

$ ferret config set browser-open true

And then, when you launch the REPL, you will see your local browser will be automatically opened:

$ ferret exec

Once we exit the REPL, browser will be closed.

Also, you can get the current value of a particular flag:

$ ferret config get browser-open


That’s it, folks! Having a separate project for CLI helps us focus more on CLI-only features outside of the Ferret Runtime and improve its usability.

If you have any feature requests welcome to GitHub Issues or to discuss something join us on GitHub Discuss board!