Overview
The Ferret CLI provides the local command-line workflow around FQL. It can run source scripts, open an interactive shell, check and format code, debug execution, build and inspect bytecode, manage browser processes, and work with Ferret modules.
Run an expression without creating a file:
ferret run --eval 'return 1 + 2'The command prints the serialized result:
3
Typical workflow
- Follow Installation and verify the CLI with
ferret version. - Use Run for scripts and inline expressions, or REPL while exploring FQL interactively.
- Run Check before execution and Fmt when source should use the canonical format.
- Use Debug for breakpoints, stepping, and variable inspection.
- Use Build to create a bytecode artifact and Inspect to examine compiled output.
Command groups
| Area | Commands |
|---|---|
| Execute FQL | Run, REPL |
| Validate and format | Check, Fmt |
| Debug and inspect | Debug, Build, Inspect |
| Browser processes | Browser |
| Modules and compatibility | Mod, Migrate |
| Persistent settings | Configuration |
Run ferret <command> --help for the flags accepted by a specific command.
Runtime and browser boundaries
The CLI uses its builtin Ferret runtime by default. The runtime owns FQL parsing, compilation, module behavior, parameter semantics, execution, and result serialization. The CLI owns command parsing, source selection, runtime selection, persistent settings, logging, and local browser-process management.
Run can send source queries to a Worker-compatible HTTP runtime with --runtime. Remote runtimes execute source queries; compiled artifacts and interactive debugging require the builtin local runtime.
Browser-backed FQL also depends on the selected runtime and its registered modules. The Browser commands start and stop managed Chrome or Chromium processes, while runtime and FQL options select how a script uses the browser.
Configuration and logging
All commands accept --log-level, --log-output, and --log-file. The config command persists supported settings in $HOME/.ferret/config.yaml.
Settings can also come from environment variables with the FERRET_ prefix. Command-line flags take priority over environment variables, which take priority over the configuration file and builtin defaults.