Run
The run command executes a FQL script and prints the result to stdout. It is also available as ferret exec.
Run a script file
ferret run script.fqlEvaluate an inline expression
Use --eval (or -e) to run a FQL expression directly:
ferret run -e 'RETURN 1 + 2'The --eval flag cannot be combined with a file argument.
Read from stdin
Pipe a script through stdin:
cat script.fql | ferret runRun a compiled artifact
Compiled .fqlc artifacts produced by ferret build can be executed directly:
ferret run script.fqlcThe CLI auto-detects whether the input is FQL source or a compiled artifact. Artifacts require the builtin runtime and cannot be used with a remote runtime.
Pass parameters
Use --param (or -p) to pass named values into a script. Parameters are accessible as @name in FQL:
ferret run script.fql --param url=https://example.com --param limit=50Values are parsed as JSON when possible, otherwise treated as strings:
| Example | Parsed as |
|---|---|
--param name=Steve |
String "Steve" |
--param age=42 |
Number 42 |
--param active=true |
Boolean true |
--param tags='["admin","editor"]' |
Array ["admin", "editor"] |
--param user='{"name":"Ada"}' |
Object {"name": "Ada"} |
--param code='"123"' |
String "123" (quoted to prevent number parsing) |
The --param flag can be repeated to pass multiple parameters.
Runtime and browser flags
These flags control where and how scripts execute. They are shared by the run, repl, and debug commands.
| Flag | Default | Description |
|---|---|---|
-r, --runtime |
builtin |
Runtime type: builtin or a remote URL |
--runtime-fs-root |
Current working directory | File system root for the runtime |
--proxy |
Proxy server address | |
--user-agent |
Custom User-Agent header | |
-d, --browser-address |
http://127.0.0.1:9222 |
Browser remote debugging address |
-B, --browser-open |
false |
Open a visible browser for script execution |
-b, --browser-headless |
false |
Open a headless browser for script execution |
-c, --browser-cookies |
false |
Persist cookies between queries |
Browser modes
Scripts that do not use browser-backed features run without a browser. When a script needs a browser, choose one of:
Automatic browser — the CLI starts and stops a browser for each run:
ferret run --browser-headless script.fqlExisting browser — connect to a browser that is already running:
ferret run --browser-address http://127.0.0.1:9222 script.fqlManaged browser — start a long-lived browser with ferret browser open and reuse it across runs.
Remote runtime
To execute against a remote Ferret runtime instead of the local builtin engine:
ferret run --runtime http://localhost:8080 script.fqlRemote runtimes cannot run compiled artifacts or debug sessions.
All runtime and browser flags can also be set persistently through the config command or environment variables.