Use a Wire runtime
Use Wire when a separate application owns the Ferret engine, custom functions, modules, and runtime configuration that your script needs. The CLI sends source and parameters to that host:
ferret run --runtime wire --runtime-endpoint tcp://127.0.0.1:54321 --eval 'RETURN 42'
Replace the endpoint with the one printed by your host. Use run, its exec alias, or repl for source execution. Use Debug for an interactive session with a local source file. Builtin execution is the default.
Install the published CLI, v2.0.0-alpha.48, before starting the host below.
Start a development host
The CLI development example exposes a configured native engine through the Universal API and Wire. It adds a host-only DEMO::IDENTITY(value) function and prints an ephemeral IPv4 loopback endpoint.
In terminal 1, start the host from the matching source tag:
git clone --branch v2.0.0-alpha.48 --depth 1 https://github.com/MontFerret/cli.gitcd cligo run ./examples/wire-host
The commands require Go 1.26.5 or later. Example endpoint:
tcp://127.0.0.1:54321
In terminal 2, run the installed CLI using the endpoint printed by terminal 1:
ferret run --runtime wire --runtime-endpoint tcp://127.0.0.1:54321 --eval 'RETURN DEMO::IDENTITY(@value)' --param value=42
It prints 42. The function runs on the host; the CLI does not register it locally. Stop the example host with Ctrl+C when finished.
For a host you build into your own application, see Remote runtimes (Wire).
Compatible host versions
This integration uses the following compatible dependency set:
| Dependency | Version |
|---|---|
| Ferret Core | v2.0.0-alpha.62 |
| Universal API | v1.0.0-alpha.21 |
| Wire | v1.0.0-alpha.4 |
| gRPC | v1.84.0 |
The host must provide runtime version metadata and support output framing version 1, introduced in Wire alpha.3. Alpha.1 and alpha.2 hosts are incompatible. The CLI verifies metadata and framing during the startup handshake, before executing source, with no buffered-output fallback.
The alpha.4 host in the compatible set above preserves preparation diagnostics, including syntax errors, so the REPL can recover and accept the next query. Pin a compatible set; Wire remains pre-stable.
Run files, stdin, and parameters
After placing a Wire-capable ferret binary on your PATH, use the same source forms as builtin execution:
ferret exec --runtime wire --runtime-endpoint tcp://127.0.0.1:54321 script.fqlcat script.fql | ferret run --runtime wire --runtime-endpoint tcp://127.0.0.1:54321
Input files are read by the CLI. It sends their source name and contents to the host, where compilation and execution happen. The CLI creates no local engine for Wire execution. Compiled artifacts require the builtin runtime. For a local FQL source file, the debug command uses the same Wire connection settings.
Parameters use the same JSON-aware parsing in builtin and Wire modes. Null, arrays, objects, and explicitly quoted strings retain their values:
ferret run --runtime wire --runtime-endpoint tcp://127.0.0.1:54321 --eval 'RETURN DEMO::IDENTITY(@value)' --param value='{"items":[42,null,"123"]}'ferret run --runtime wire --runtime-endpoint tcp://127.0.0.1:54321 --eval 'RETURN @code' --param code='"123"'
Use the interactive shell
ferret repl --runtime wire --runtime-endpoint tcp://127.0.0.1:54321
For the example host, the banner and a submission look like:
Welcome to Ferret REPL (Wire runtime: tcp://127.0.0.1:54321; version: v2.0.0-alpha.62)
Please use `exit` or `Ctrl-D` to exit this program.
> RETURN DEMO::IDENTITY(42)
42
The REPL opens one runtime and transport pair and reuses it for every submission. Query diagnostics go to stderr; correct the query and submit again. Transport loss or resource failure ends the shell with an error. It does not reconnect, retry a query, or fall back to builtin execution.
The existing editing and multiline conventions apply. Use exit or Ctrl+D to exit; Ctrl+C stops the shell, including pending input or execution.
Read the hosted version
ferret version --runtime wire --runtime-endpoint tcp://127.0.0.1:54321
The command preserves the normal output format:
Version:
Self: <cli-version>
Runtime: v2.0.0-alpha.62
Self identifies the CLI. Runtime and the Wire REPL banner use the exact version supplied by the hosted Universal API runtime. The value is opaque and is preserved without parsing or normalization, including an empty value. The development example derives it from its Ferret dependency’s Go build information. Builtin execution uses the CLI’s injected runtime version, or unknown in a build without version injection.
Wire captures metadata during the initial handshake. A failed or stalled metadata request fails connection construction within the connection timeout, before the REPL reads input. Later version reads use the captured value and make no extra RPC. The version command accepts runtime selection flags without adding browser or policy flags.
Configure the connection
| Flag and config key | Environment variable | Default |
|---|---|---|
runtime |
FERRET_RUNTIME |
builtin; select wire explicitly |
runtime-endpoint |
FERRET_RUNTIME_ENDPOINT |
Required in Wire mode; no default port |
runtime-connect-timeout |
FERRET_RUNTIME_CONNECT_TIMEOUT |
5s; must be strictly positive |
Only tcp://127.0.0.1:<port> is accepted, with a port from 1–65535. Other hosts, schemes, userinfo, paths, queries, and fragments are rejected before connecting. Endpoint and connection-timeout settings require Wire mode.
The timeout bounds connection establishment and the Wire handshake, including hosted metadata retrieval. It does not set a query execution timeout. Command cancellation interrupts connection setup and active work.
These settings are shared by run, exec, repl, debug, and version. Configuration precedence remains flags, environment variables, config file, then defaults. To persist a Wire connection:
ferret config set runtime wireferret config set runtime-endpoint tcp://127.0.0.1:54321ferret config set runtime-connect-timeout 5s
To restore builtin selection, unset the Wire-specific settings as well:
ferret config set runtime builtinferret config unset runtime-endpointferret config unset runtime-connect-timeout
config unset removes persisted values; environment variables still take precedence. The example host selects a new ephemeral port each time it starts, so update any saved endpoint after restarting it.
Host policies and filesystem ownership
The host owns its functions, modules, filesystem, HTTP policy, and browser integrations. FQL filesystem operations run against the host’s configured filesystem; the CLI does not send its working directory as a filesystem-root override. The development host uses its own working directory as its filesystem root. Reading a local input script is separate from filesystem access inside that script.
Wire mode rejects explicitly supplied builtin filesystem/HTTP policies and browser settings, including values in config files or environment variables. Even an explicit default-valued flag such as --browser-headless=false counts as configuration. Untouched defaults remain acceptable. Configure those capabilities on the host, and remove incompatible client settings before connecting.
Each command owns one logical runtime and transport. Active calls settle before cleanup closes the runtime, then the transport. Closing the CLI connection leaves the host engine usable. After cancellation, Wire uses detached cleanup bounded by its 30-second cleanup timeout; cleanup failures remain part of the reported error.
This CLI transport uses plaintext loopback for trusted local development, without authentication or TLS. Local access does not authenticate the client or host. HTTP headers and policy flags are not Wire credentials.
Output and diagnostics
run consumes the host’s encoded output and writes its chunks to stdout without decoding or re-encoding them, collecting the whole result, or adding a connection banner. It waits for consumption to finish and checks terminal execution, delivery, and cleanup errors before reporting success. Available output is written even when execution also returns an error. Successfully produced empty output emits nothing. Errors and source diagnostics go to stderr and cause a failing command exit.
Chunks are delivered synchronously, so stdout provides backpressure. The REPL finishes each query’s output before starting another. Streaming encoded bytes does not imply incremental FQL evaluation.
To inspect an intentionally invalid query, run:
ferret run --runtime wire --runtime-endpoint tcp://127.0.0.1:54321 --eval 'LET arr = []RETURN'
The host reports the source location, RETURN line, insertion caret after the keyword, and missing-value hint. RETURN ) highlights the actual invalid token. In the REPL, these query errors allow a corrected submission; connection failures require checking the host and starting a new command.