Ferret CLI

This branch contains the CLI for Ferret v2. For the stable v1 CLI, see the v1 branch.

What is this?

Ferret CLI is the command-line interface for Ferret, a declarative query language and runtime for structured data extraction, browser automation, and data workflows.

Use it to run FQL scripts, format and check source files, inspect compiled bytecode, manage browser sessions, and debug local scripts.

Full documentation lives at ferretlang.org.

Installation

Download a release from the releases page, or install from source:

go install github.com/MontFerret/cli/v2/ferret@latest

Shell installer:

curl https://raw.githubusercontent.com/MontFerret/cli/master/install.sh | sh

Quick start

Run the REPL:

ferret repl

Run an inline expression:

ferret run --eval 'RETURN "Hello, Ferret!"'

Run a script:

ferret run example.fql

Pass parameters:

ferret run example.fql --param url=https://example.com --param limit=10

Parameter values are parsed as JSON when possible. Values that are not valid JSON are passed as strings.

ferret run example.fql --param active=true
ferret run example.fql --param tags='["news","tech"]'
ferret run example.fql --param code='"123"'

Use parameters in FQL with @name:

LET page = DOCUMENT(@url)

RETURN ELEMENT(page, "title").innerText

Common commands

ferret run script.fql       # Run a script
ferret exec script.fql      # Alias for run
ferret repl                 # Start the interactive shell
ferret check script.fql     # Check syntax and semantics
ferret fmt script.fql       # Format source
ferret build script.fql     # Compile to a bytecode artifact
ferret inspect script.fql   # Print compiled program details
ferret debug script.fql     # Start the interactive debugger
ferret browser open         # Start a managed browser
ferret config list          # Show configuration
ferret version              # Show version information

Run ferret [command] --help for command-specific options.

Browser usage

Ferret can use Chrome or Chromium through the Chrome DevTools Protocol.

Open a managed browser:

ferret browser open

Run a script with a visible browser:

ferret run --browser-open script.fql

Run with a headless browser:

ferret run --browser-headless script.fql

Use an existing browser endpoint:

ferret run --browser-address http://127.0.0.1:9222 script.fql

Debugging

Start the debugger for a local source file:

ferret debug script.fql

Useful debugger commands:

break 12        Set a breakpoint
breakpoints     List breakpoints
continue        Resume execution
step            Step into
next            Step over
out             Step out
where           Show stack trace
locals          Show local variables
print <expr>    Evaluate a safe debug expression
quit            Exit

The debugger currently supports local source scripts with the builtin runtime. Compiled artifacts, remote debugging, DAP, conditional breakpoints, hit-count breakpoints, and logpoints are not supported yet.

Configuration

Configuration values can come from command-line flags, environment variables, or the config file.

Priority order:

1. Command-line flags
2. Environment variables, for example FERRET_RUNTIME
3. Config file
4. Defaults

Config file locations:

• Linux/macOS: ~/.config/ferret/config.yaml
• Windows: %APPDATA%\ferret\config.yaml

Examples:

ferret config set runtime builtin
ferret config set browser-address http://127.0.0.1:9222
ferret config get browser-address
ferret config list

Development

Build and test locally:

git clone https://github.com/MontFerret/cli.git
cd cli

make compile
make test

Common development commands:

make fmt
make lint
make build

Contributing

Issues and pull requests are welcome. Before opening a pull request, run the formatter, linter, and test suite.

License

Apache-2.0