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, its exec alias, and REPL can execute source against an application-configured Wire runtime with --runtime wire --runtime-endpoint tcp://127.0.0.1:<port>. The host owns compilation, modules, policies, browser integrations, and FQL filesystem access. The CLI also retains Worker-compatible HTTP URL execution through --runtime. Compiled artifacts and interactive debugging require the builtin local runtime.
ferret version reports the CLI and selected runtime versions. In Wire mode it reads the hosted Universal API version during the initial handshake; the REPL banner shows that version and endpoint.
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.