Aether Term (REPL)

ToolsCLIREPLScripting

Stable On by default · production-ready

What it is

Aether Term is the official command-line client for AetheriusDB and the shell used throughout Install and the Quickstart. It opens an interactive prompt, accepts SQL and AetherScript statements, and prints results in a familiar bordered-table layout.

If you have ever used psql, the experience is intentionally identical: tab-completion against the live catalog, persistent history across sessions, and a full set of slash-commands for inspecting tables and schemas. It starts instantly and stays responsive over slow links.

Where Aether Term goes beyond a classic SQL shell is in how it renders cube-shaped and tensor-shaped results. Instead of flattening everything to two dimensions, it detects when a query returns a multi-dimensional cube or a vector column and formats it hierarchically so the output stays readable.

Why it matters

DBAs and CI/CD pipelines need a client that is fast, predictable, and scriptable.

• Familiar muscle memory — every \ command from psql has a working equivalent, so existing run-books port unchanged.
• Lossless output — multi-dimensional and tensor results are not flattened or truncated; you see what the engine actually returned.
• Headless mode — -c for one-shot statements and stdin streaming for piping SQL from files or other tools.

How you use it

Launching the shell connects to the local database by default. Once at the prompt you can mix interactive exploration with slash-commands, and use the same binary in scripts.

# Start an interactive session against the local node
aether-term

Inside the REPL, list tables, describe one, run a query, and quit:

-- List tables, then describe one
\dt
\d orders

-- Run a query; multi-dimensional output formats hierarchically
SELECT region, product, SUM(amount)
FROM sales
GROUP BY region, product;

-- Quit cleanly
\q

The same binary covers the three common modes — interactive exploration, one-shot from a shell pipeline, and bulk script execution from a file:

# Headless: one-shot statement, exits with a status code
aether-term -c "SELECT count(*) FROM orders"

# Stream a script file through stdin
cat migrate.sql | aether-term

Slash-commands and history

Concept	What it does
Slash-command	A meta-command like \dt or \d that introspects the live catalog without writing SQL. Run \? to list them.
Headless mode	Non-interactive use via -c or stdin; suitable for cron jobs and CI pipelines.
Hierarchical output	Cube and tensor results print with structure preserved rather than collapsed to a flat grid.
History file	Statements persist across sessions in your home directory; up-arrow recall works as expected.

Tip

If you live in psql, run \? at the prompt to see the supported meta-commands. Unfamiliar commands suggest the closest Aetherius equivalent rather than silently failing.

Very large result sets

Large result sets paginate through less. For multi-gigabyte exports, use the bulk-export path rather than scrolling through the terminal.

Connecting to remote databases

By default Aether Term connects to the local node. To reach a remote database, pass --host. The client automatically negotiates the fastest available transport — the native high-throughput path when the network allows it, and the PostgreSQL-compatible path when it does not — so a single command line works against a fresh local node, a hardened cloud cluster, or a laptop tunneling through a VPN. The active mode is shown in the prompt itself, so you always know which transport you are on.

# Default: auto-negotiate. The prompt indicates the chosen mode.
aether-term --host db.example.com
# AESQL (Native) >

# Force PostgreSQL-compatibility mode (skip the native probe)
aether-term --host db.example.com --protocol pgwire
# AESQL (Postgres Fallback) >

# Lock to native, fail loudly if it is blocked
aether-term --host db.example.com --protocol native --strict

Inspect the negotiated transport from inside the REPL with \conninfo.

Flag	Effect
--host <ADDR>	Connect to a remote database instead of the local node.
--protocol native	Use the native high-throughput protocol.
--protocol pgwire	Use the PostgreSQL-compatible protocol; works with any pgwire tool.
--strict	Refuse to fall back. Fail loudly if the requested transport is unavailable.

Tip

In strict environments where the native path is explicitly blocked, pin the CLI to --protocol pgwire in your shell profile to skip the probe entirely and shave a few milliseconds off connection setup.

Native-only features

A few features (such as time-travel result streaming) are only available in native mode. The CLI warns rather than fails when you invoke them under the PostgreSQL fallback.

Connect a Client →

Driver options across Python, JDBC, and Arrow Flight SQL.

Quickstart →

End-to-end walkthrough from empty database to first query.

Install →

Install the CLI and configure the listening port.

AetherScript →

The language you can run from the prompt.