The command line

The binary is given one store and one thing to do with it. Everything below follows from that sentence, including most of what it refuses.

Everything it takes

This is the binary's own usage, with the column a usage line has no room for.

Two of these need no store at all — --version and --verify — and that is deliberate. The first thing anyone does with a binary they have just been handed is ask what it is, and a backup that can only be checked by restoring it is a backup nobody checks.

An unknown option is an error, not something ignored:

$ tessaridb --nonsense
unknown option "--nonsense"

A session opened with a misspelled flag that quietly used the default is how somebody writes to the wrong store. The same reasoning produces the refusals further down.

Running a script

Three ways in, and the store cannot tell them apart:

$ tessaridb ./data -e 'USE NAMESPACE prod; USE DATABASE orders; SELECT name FROM users;'
$ tessaridb ./data -f migrate.tessariql
$ cat migrate.tessariql | tessaridb ./data

.tessariql is the conventional extension. Nothing reads it — -f takes any path. The same three, worked through from an empty store, are Run a file instead of typing.

With neither -e nor -f, statements are read from standard input: a prompt when that is a terminal, a script when it is a pipe. The pipe gets no prompt and no greeting, so what comes back is the script's output rather than a transcript of a session:

$ tessaridb ./data -f first.tessariql
ok
ok
ok
ok
ok
ok
1: { name: 'ada' }
(1 record(s), via scan)

One ok per statement that answered nothing. A statement that answers with records prints them, then how many there were and how they were reached.

A script is not a transaction

This is the part worth reading before a migration.

A script runs statement by statement and stops at the first refusal, with exit 1. What ran before the refusal has already happened, and nothing undoes it. The boundary is not the file — it is wherever you put BEGIN.

Four scripts, each run against its own empty store on disk, and each store read back afterwards:

The last row differs from the second because of where the statements were cut. A file is read a statement at a time, so the lines before the bad one have already gone to the store. A whole -e string on one line is submitted as one piece, so it is parsed before any of it runs, and one bad token anywhere means none of it does. Both are defensible; they are not the same, and a migration that assumes one and gets the other lands halfway.

So the way to say all of it or none of it is to say so:

DEFINE COLLECTION staff;
BEGIN;
CREATE staff = { name: 'ada' };
CREATE staff = { name: 'grace' };
COMMIT;
SELECT name FROM staff;

A transaction spanning several lines of a file is held together as one — the ; after BEGIN does not end it. And a statement outside BEGIN is its own transaction, which is why the first row of that table leaves a record behind rather than nothing: see Transactions.

The password is not an argument

There is no --password, and that is the feature:

$ tessaridb --at 127.0.0.1:7654 --user editor --password hunter2
unknown option "--password"

An argument is readable by anyone who can list processes on the machine, and it outlives the session in the shell history. The password is read from TESSARIDB_PASSWORD instead, and --user says so when it is missing:

$ tessaridb --at 127.0.0.1:7654 --user editor
tessaridb: --user needs the password in TESSARIDB_PASSWORD, and it is not set

Who the users are and what each may do is Users.

Values that come from outside the script

--param binds one parameter, and repeats:

$ tessaridb ./data --param "who='ada'" --param 'limit=10' -f report.tessariql

The value is written as TessariQL, not JSON, so dec 12.34, 2s and datetime '…' all say what they are — and what an answer prints pastes straight back into the next parameter. It is read in isolation, as a value and nothing else:

$ tessaridb --param 'x=1; DROP TABLE users' -e 'SELECT * FROM users;'
--param x: "1; DROP TABLE users" is not a value TessariQL can read on its own

That reader is shared with the parameters field of an HTTP request body, so the two surfaces cannot drift into reading a supplied value differently. Why nothing a caller supplies can become syntax — bound after the statement is read, rather than escaped into it — is Parameters.

What a running node reports

TESSARIDB_LOG sets how much a node says on standard error — one line per event, with a UTC timestamp, the level, the source, the spans it happened inside and a sentence, followed by its values as named fields:

2026-10-04T14:32:45.138963Z  INFO tessaridb::serving::announcing: serving the wire protocol address=127.0.0.1:9080
2026-10-04T14:33:02.511207Z  WARN connection{connection=7}: tessari_session::session::signing: sign-in refused user=ada

A value is never spliced into the sentence, so user=ada or connection=7 can be searched for, and every line a connection produced carries its number.

info is the default rather than warn because a node that reports only its problems cannot answer was it even reached — which is the first question when a client sees nothing.

Besides one level, TESSARIDB_LOG takes per-module directives — info,tessari_wire=debug reports the wire protocol in detail and everything else at info. A value it cannot read is reported once and info is used.

TESSARIDB_LOG_FORMAT chooses the shape: text (the default) for a person, or json for a collector — one object per line, the event's fields flattened beside timestamp, level, target and message, and the spans it happened in under spans. Colour is used only when standard error is a terminal and NO_COLOR is not set.

A value it cannot read is not an error. It reports at the default and starts normally; refusing to open a database because a log level was misspelled would be the worse of the two outcomes.

The node's own timers

What a node does on a timer — housekeeping, the cluster's greeting, collection, campaign, settling and balancing rounds, the credential watch — runs one pass at a time, and every line a pass produces carries cadence{cadence=…}. Each pass ends one of three ways: it completes (said at debug, because it happens every period), it fails — pass failed, with what it could not do and why — or it overruns its period — pass overran, said once; the next pass waits for it rather than running beside it. A failed pass does not stop the timer.

2026-10-05T03:12:09.402117Z  WARN cadence{cadence="collection"}: tessari_wire::driver::cadence: pass failed elapsed_ms=3 error=the collection pass failed: this node cannot say who its peers are: …

Arguments that are refused together

Each of these could have been resolved by ignoring something. None of them is, because a value silently dropped is a value somebody believes was used — and here what they believe is that a port is open, or that a backup was bounded.

The five cluster options are given together or not at all. Told some of them, a node refuses to start rather than serving with credentials nobody checked; told none of them, it is the single node it is today. There is no default peer address, because there is no port this engine claims and a defaulted listener is a door the operator did not know they opened.

--version and --help are the exception: they name this binary rather than the node at --at, so an address alongside them is neither refused nor consulted.

Exit codes

Two of them are meant to be read by a script rather than a person. --health exits non-zero when the store is unwell, so a cron line needs no output parsing:

$ tessaridb ./data --health
well — committed to sequence 0

And --verify exits non-zero on a backup that was cut short, which is the condition you are verifying for — the warning is on the error stream, so a script can act on the status without reading either:

$ tessaridb --verify ./monday.tessarilog
0 record(s), sequences 1..=5, good through 0
warning: ./monday.tessarilog was cut short — it says it holds through 5 and reads through 0
$ echo $?
1

Where in a backup routine to put that call — and why it is before the file is moved into place — is Checking one.