CLI reference

The standalone OrchidDB-cli bundles DuckDB and loads the official Iceberg extension by default. It compiles graph reads to SQL and returns Arrow results.

Install

Install the released v0.1.0 CLI on macOS ARM64 (Apple Silicon):

curl -fsSL https://install.orchiddb.com | bash
export PATH="$HOME/.local/bin:$PATH"
orchiddb --version

See installation for pinned versions, direct downloads, and source builds. The quickstart provides complete input files and runs with the installed binary, without a repository checkout.

Invocation

orchiddb compile REQUEST.json
orchiddb query REQUEST.json [--database FILE] [--init SQL_FILE] [--format arrow|table] [--no-iceberg]
orchiddb --version

REQUEST.json uses compiler protocol version 1, including language, query, dialect, table schemas, and graph mappings. The CLI executes DuckDB SQL only. compile prints SQL without opening a database or installing extensions.

Query options

Option	Description	Default
`--database FILE`	DuckDB database path	In-memory database
`--init SQL_FILE`	Run caller-supplied setup SQL before the query	No setup
`--format arrow`	Arrow IPC stream on stdout	Default output
`--format table`	Human-readable output, one batch at a time	Opt-in
`--no-iceberg`	Skip Iceberg installation/loading	Iceberg enabled

Use space-separated option values. The request is a file, not inline query text. This binary does not accept the legacy managed CLI’s --query, --language, or --explain flags.

Run a query

Save people.json and setup.sql from the quickstart, then run:

orchiddb query people.json --init setup.sql --format table --no-iceberg
orchiddb compile people.json
orchiddb query people.json --init setup.sql --no-iceberg > people.arrow

The setup creates source tables and the request maps them to a Person label. Arrow IPC goes to stdout; errors go to stderr. A failure returns a nonzero exit status. See the quickstart for complete input files.

Iceberg and engine setup

Queries first load the cached Iceberg extension or install the signed official extension from DuckDB’s extension service. Installation failure is reported; there is no silent fallback. Use --no-iceberg for queries that do not need Iceberg.

Your initialization file can configure credentials, plugins, UDFs, attached catalogs, and views:

CREATE VIEW people AS
SELECT id, name FROM iceberg_scan('/path/to/table/metadata/v1.metadata.json');

Map that view in your request. Actual storage access requires your own credentials and catalog setup. Setup SQL is executed as supplied. The CLI owns its database connection; applications that already own an engine should use a language client.

Managed runtime CLI

Core retains a separate legacy binary behind --features duckdb, used by some managed graph examples. Its mutation/query flags are different. The CLI described here executes generated read SQL; it does not expose graph mutations. Match command usage and conformance evidence to the executable revision.

Keyboard shortcuts