CLI Overview
LynxDB ships as a single binary. The same executable provides:
- ad hoc analytics on local files and stdin
- a persistent server
- a Web UI launcher
- administrative commands for auth, status, cache, config, jobs, and views
lynxdb [command] [flags]
Modes of Operation
The CLI changes behavior depending on the command and on whether stdin is piped.
Server mode
lynxdb server
Starts the HTTP server. Commands such as query, ingest, status, fields, jobs, and mv then talk to that server over HTTP.
Local file mode
lynxdb query --file access.log '| stats count() by status'
Queries files directly without a running server. LynxDB creates an ephemeral in-memory engine, ingests the matching file set, runs the query, prints results, and exits.
Stdin pipe mode
cat app.log | lynxdb query '| stats count() by level'
This is the same ephemeral execution path as file mode, but the input comes from stdin.
Bare stdin mode
If stdin is piped and you run lynxdb with no subcommand, LynxDB defaults to a preview query:
cat app.log | lynxdb
That runs the equivalent of | head 10 after format detection.
If stdin is piped and the first argument is not a known subcommand, LynxDB treats the remaining arguments as a query:
cat app.log | lynxdb 'where level == "error" | stats count() by source'
Global Flags
Available on all commands:
| Flag | Short | Default | Env Var | Description |
|---|---|---|---|---|
--config | (auto) | Path to config file | ||
--server | http://localhost:3100 | LYNXDB_SERVER | LynxDB server address | |
--token | LYNXDB_TOKEN | API key for authentication | ||
--profile | -p | LYNXDB_PROFILE | Connection profile name | |
--format | -F | auto | Output format: auto, json, ndjson, table, box, ascii, markdown, vertical, line, G, csv, tsv, raw | |
--quiet | -q | false | Suppress non-data output | |
--verbose | -v | false | Show extra detail | |
--no-stats | false | Suppress query statistics | ||
--no-color | false | Disable colored output | ||
--theme | auto | Human output theme: auto, dark, light, plain | ||
--compact | false | Use compact human output | ||
--max-rows | 0 | Maximum rows to show in human table output (0 = all) | ||
--max-width | 0 | Maximum width for human table output (0 = terminal width) | ||
--null-value | Placeholder for null or empty values in human table output | |||
--debug | false | Enable debug logging to stderr | ||
--tls-skip-verify | false | LYNXDB_TLS_SKIP_VERIFY | Skip TLS certificate verification |
Output Mode
With --format auto, LynxDB chooses a human-friendly format for interactive terminals and a machine-friendly format when stdout is piped. Use --format to force a stable format for scripts.
# Stable JSON for scripts
lynxdb query 'from main level=error | stats count() by source' --format json
# Stable CSV export
lynxdb query 'from main level=error | stats count() by source' --format csv
# Human-readable table output
lynxdb query 'from main level=error | stats count() by source' --format table
# Vertical output for wide rows
lynxdb query 'from main level=error | head 2' --format vertical
NO_COLOR disables colored output when set. --format line and --format G
are aliases for vertical output; the query suffix \G also switches auto
format to vertical output.
Exit Codes
The root command advertises these exit codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage error |
| 3 | Connection error |
| 4 | Query parse error |
| 5 | Query timeout |
| 6 | No results (--fail-on-empty) |
| 7 | Authentication error |
| 10 | Aborted by user |
| 130 | Interrupted |
Command Map
Some commands have dedicated reference pages in this documentation set. Others are currently discoverable via lynxdb <command> --help.
| Category | Commands |
|---|---|
| Querying and ingest | query, ingest, import, tail, fields, count, sample, watch, diff, last, explain, examples |
| Server and operations | server, status, health, indexes, cache, jobs, doctor, shippers |
| Saved objects | mv, saved, save, run |
| Authentication and connection | login, logout, auth, config |
| Interactive and UI | shell, ui, open, share, top |
| Setup and maintenance | init, install, uninstall, upgrade, version, completion, admin format-upgrade |
| Diagnostics and misc | bench, demo, grammar, explain-error, sigma |
Migration Hints
LynxFlow v2 replaced the legacy SPL2 language. When a query uses a removed SPL2 stage, the parser rejects it with a targeted error and a suggestion for the v2 equivalent:
error[E011] at 1:3: eval is renamed to extend in v2
| eval is_slow = duration_ms > 1000
^~~~
suggestion: extend
Run lynxdb examples for a built-in query cookbook.