Skip to main content

CLI Overview

LynxDB ships as one binary, lynxdb. It runs the server and is also the client for it. Queries are written in PPL, the OpenSearch Piped Processing Language.

lynxdb [command] [flags]

Where a query runs​

lynxdb query runs a query in one of two places.

ModeTriggerWhat happens
ServerDefaultThe CLI sends the query to POST /api/v1/query on the server named by --server and prints the rows it returns.
Local--file <path or glob>, or piped stdinThe CLI opens a database of its own in a temporary directory, loads the input into the index main, runs the query in process and removes the directory on exit. No server is involved.

Both modes compile the same PPL text with the same compiler and run it on the same engine, so a query that works against a file works against the server.

# Server
lynxdb query 'source=main level=ERROR | stats count() as errors by host'

# Local file
lynxdb query --file access.log 'source=main | stats count() by status'

# Standard input
kubectl logs deploy/api | lynxdb query 'source=main | where response_time > 500 | stats count() by path'

The query page covers flags, time ranges and how local input is loaded.

Bare stdin​

Run lynxdb without a subcommand and with piped stdin to load the input and print its first ten events (source=main | head 10):

cat app.log | lynxdb

When the first argument is not a command name, the arguments form a query over stdin:

cat app.log | lynxdb 'source=main | stats count() by level'

Without piped stdin, a bare query fails with a hint to pipe input, and plain lynxdb prints a short welcome screen.

Global flags​

These flags work with every command.

FlagShortDefaultEnv varDescription
--serverhttp://localhost:3100LYNXDB_SERVERServer address
--tokenLYNXDB_TOKENAPI key sent as a bearer token
--profile-pLYNXDB_PROFILEConnection profile from the config file
--configautoLYNXDB_CONFIGConfig file path (server, config commands, profiles)
--format-FautoOutput format: auto, json, ndjson, table, box, ascii, markdown, vertical, line, G, csv, tsv, raw
--quiet-qfalsePrint data only: no hints, progress, statistics or error messages
--verbose-vfalseShow extra detail, such as the full statistics block after a query on a terminal
--no-statsfalseDo not print query statistics
--no-colorfalseDisable color (NO_COLOR with any value does the same)
--themeautoHuman output theme: auto, dark, light, plain
--compactfalseTighter human output
--max-rows0Rows shown in human table output (0 = all)
--max-width0Width of human table output (0 = terminal width)
--null-valuePlaceholder for null or empty values in human table output
--debugfalseDebug logging to stderr
--tls-skip-verifyfalseLYNXDB_TLS_SKIP_VERIFYSkip TLS certificate verification (true, 1 or yes in the env var)

lynxdb import uses --format for its input format, and lynxdb login uses --token for the key to save; on those two commands the global flag of the same name is not available.

See Output Formats for what each format prints.

Connection settings​

The CLI resolves the server address in this order, first match wins:

  1. --server
  2. The URL of the selected profile (--profile, then profile in .lynxdbrc, then LYNXDB_PROFILE)
  3. server in the nearest .lynxdbrc
  4. LYNXDB_SERVER
  5. http://localhost:3100

The API key comes from --token, then LYNXDB_TOKEN, then the credentials file that lynxdb login writes (lynxdb/credentials.yaml under the user config directory, keyed by server URL).

Project defaults: .lynxdbrc​

The CLI looks for a .lynxdbrc YAML file in the current directory and each parent. Values apply only when the matching flag is not given:

server: https://logs.example.com
profile: prod
default_format: table
default_since: 6h
default_source: web
KeyApplies to
server--server
profile--profile
default_format--format
default_sincelynxdb query --since
default_source--source on query, ingest and import

.lynxdbrc holds client defaults only. Server settings live in the config file; see config.

Commands​

AreaCommands
Queryquery (q), explain, fields (f)
Load dataingest (i), import
Run the serverserver
Inspect the serverstatus (st), health, indexes, jobs
Authenticationlogin, logout, auth
Configurationconfig
Utilitiesversion, completion

Every command prints its flags and examples with lynxdb <command> --help.

Exit codes​

CodeMeaning
0Success, including a confirmation prompt answered with no
1Any other failure: an unknown flag, a missing argument, an execution error on the server, a bad file
2A required flag is missing, for example lynxdb auth create without --name
3The CLI cannot connect to the server
4The query does not compile: a PPL syntax, semantic, type, planning or unsupported-feature error, reported by the server or by local compilation. Any other HTTP 400 answer, such as QUERY_TOO_LARGE or VALIDATION_ERROR, also exits with 4
5The query timed out (--timeout, the CLI's 6-minute default, or a server timeout)
6The query returned no rows and --fail-on-empty was set
7The API key is missing, invalid or lacks the scope for the request
130Interrupted with Ctrl+C (the shell reports a process stopped by SIGINT as 130)

PPL errors lists the compile error codes and their messages.

lynxdb query 'source=main level=FATAL' --since 1h --fail-on-empty --quiet < /dev/null > /dev/null
case $? in
0) echo "fatal errors found" ;;
6) echo "no fatal errors" ;;
3) echo "server unreachable" ;;
4) echo "query does not compile" ;;
*) echo "query failed" ;;
esac