Interactive REPL

Launch with any connection — a raw URL, a profile name, or a saved registry entry:

ferrule repl "sqlite::memory:"
ferrule repl demo
ferrule repl prod

The REPL is a TTY-only experience. If you need batch input from a script, use ferrule query --stdin instead (see Querying).

What you get

Readline editing via rustyline — arrow keys, line editing, Ctrl-R reverse history search, Ctrl-A / Ctrl-E for line endpoints.
Multi-line SQL. Statements that span multiple lines are collected until a trailing ;. Cancel a partially-typed statement with Ctrl-C.
Persistent history at ~/.cache/ferrule/history. Shared across sessions for the current user.
Session parameters (\param) and bookmarks (\bookmark) work the same as their CLI counterparts and share the same bookmark file.
Watch mode (\watch) re-runs the previous query on a configurable interval without leaving the REPL.

Meta-commands

Backslash prefix:

Command	Description
`\q`	Quit the REPL
`\conn [name]`	Switch connection or show current
`\d [table]`	Describe table; without an argument, behaves like `\dt`
`\dt [schema]`	List tables
`\format [fmt]`	Set output format (`table`, `json`, `csv`, `yaml`, `raw`)
`\limit [N]`	Set row limit (`0` to clear)
`\timing [on\|off]`	Toggle timing display (per-query connect/query/format breakdown)
`\verbose [on\|off]`	Toggle verbose logging (resolved URL + SQL)
`\param <name> <value>`	Set a session parameter for `${name}` placeholders
`\param clear`	Clear all session parameters
`\param list`	List currently-set parameters
`\bookmark save <name>`	Save the previous SQL as a bookmark
`\bookmark list`	List saved bookmarks
`\bookmark run <name> [args…]`	Run a bookmark with positional params
`\bookmark delete <name>`	Delete a bookmark
`\explain [<sql>]`	Explain one query, or toggle explain-everything mode
`\watch [<sql>]`	Watch a query (default 5s interval); `\watch interval N` adjusts; `\watch stop` ends
`\dump <table>`	Dump a table to stdout
`\load <file> INTO <table>`	Load a CSV/JSON file into a table
`\help`	Show in-REPL help

Example session

$ ferrule repl demo

Connected to postgres://ferrule:***@127.0.0.1:15432/ferrule
Type \help for commands, \q to quit.

ferrule> \format table
ferrule> SELECT id, name, signed_up FROM customers ORDER BY id;
┌────┬───────┬───────────────────────────────┐
│ id │ name  │ signed_up                     │
├────┼───────┼───────────────────────────────┤
│ 1  │ Alice │ 2026-04-26 18:01:23.456+00:00 │
│ 2  │ Bob   │ 2026-04-26 18:01:23.456+00:00 │
│ 3  │ Carol │ 2026-04-26 18:01:23.456+00:00 │
└────┴───────┴───────────────────────────────┘

ferrule> \timing on
Timing: on

ferrule> SELECT COUNT(*) FROM customers;
┌──────┐
│ count│
├──────┤
│ 3    │
└──────┘
[ferrule] connect: 0ms (pooled)
[ferrule] query:   2ms
[ferrule] total:   2ms

ferrule> \bookmark save customer-count
Bookmark 'customer-count' saved.

ferrule> \param email 'alice@example.com'
ferrule> SELECT * FROM customers WHERE name = ${email};
(...)

ferrule> \q

Bookmarks in the REPL

REPL bookmarks share the ~/.config/ferrule/bookmarks.toml file with CLI bookmarks. Saving from the REPL captures the previous SQL statement as the bookmark body:

ferrule> SELECT * FROM users WHERE active = true;
ferrule> \bookmark save active-users
Bookmark 'active-users' saved.

ferrule> \bookmark list
- active-users
- customer-count

ferrule> \bookmark run active-users

Positional parameters work the same as on the CLI:

ferrule> \bookmark run user-by-id 42

See Bookmarks for the full surface.

Watch mode inside the REPL

Re-run the previous query on a fixed cadence without leaving the REPL:

ferrule> SELECT COUNT(*) FROM events;
ferrule> \watch                  # repeats the COUNT(*) every 5s
ferrule> \watch interval 3       # change interval to 3s
ferrule> \watch stop             # exit watch loop

Watch prints a header on each iteration. The --diff mode (only print on change) is also supported in watch loops; see Advanced Features.

When to leave the REPL

Switch to one-shot ferrule query invocations when:

You’re scripting (no TTY).
You need --output FILE to write to a file.
You want predictable exit codes for use in && chains.

Switch to the REPL when:

You’re iterating on a query and want history + multi-line editing.
You want timing or verbose mode toggled per-statement.
You want to alternate between SQL and \d / \dt exploration.

History maintenance

Persistent history at ~/.cache/ferrule/history grows unbounded. If it gets unwieldy, truncate it manually:

tail -n 1000 ~/.cache/ferrule/history > ~/.cache/ferrule/history.new
mv ~/.cache/ferrule/history.new ~/.cache/ferrule/history

Or delete it entirely to start fresh — the file is recreated on the next REPL launch.

Keyboard shortcuts

Ferrule