graphene

graphene command [options] [arguments]

graphene is the CLI for Graphene, an everything-as-code analytics framework aimed at coding agents. A project is a directory of `.gsql` semantic models (tables, joins, dimensions, measures) and `.md` dashboard pages. The CLI compiles Graphene SQL to the warehouse dialect, runs queries, checks files, and serves pages locally.Install the published package `@graphenedata/cli` with npm, pnpm, yarn, or bun, then invoke `graphene` via that package manager (`npx graphene`, `pnpm graphene`, `npm exec graphene`). Supported warehouses include DuckDB (and MotherDuck), Postgres, Snowflake, BigQuery, ClickHouse, and Amazon Athena. Database clients are optional peer dependencies installed beside the CLI.run on a `.md` file starts the local server if needed, opens the page, writes a PNG screenshot under the project cache, and prints a `http://localhost:...` URL (default port 4000). Inline queries and stdin (`-`) run in-process and print a table or CSV. Running `.gsql` files directly is no longer supported.

check [file]

Lint `.gsql` models and markdown pages. With a path, check that file only.

Translate Graphene SQL to dialect-specific SQL and print it. Input is a file path, an inline string, or `-` for stdin.

Run a query, or open a markdown page in a browser and save a screenshot. --param may be repeated. --chart is a chart/table title or a component id from list.

Print component ids for charts and tables on a markdown page, for run -c.

List datasets/schemas, or describe a table as a Graphene SQL `table` statement. Not for exploring modeled Graphene SQL.

Start the local dashboard server. --bg detaches it.

Stop the background server started by serve --bg or run on a page.

Log in to Graphene Cloud, or trigger Snowflake auth when Cloud is not configured.

Export a synced Cloud markdown report as standalone HTML. Does not read local file contents.

Create a Graphene Cloud access token for background agents (default TTL 30d, range 5m–366d).

Read Cloud eval history as JSON (admins only).

Read completed Cloud session reviews as JSON (admins only).

Install the Playwright browser used by run --headless. Works outside a Graphene project.

Print the CLI version.

Graphene reads a `graphene` object in the project's `package.json`. Restart serve after changing it. Secrets belong in an ignored `.env` file.duckdb, motherduck, postgres, snowflake, bigquery, clickhouse, athena

Exactly one connection block. The dialect is inferred from which block is present.

Schema/dataset used for unqualified table names. Overridden by GRAPHENE_DEFAULT_NAMESPACE. Also accepted as namespace.

Local server port. Default 4000, or GRAPHENE_PORT.

`.env` path or list of paths (default `['.env']`).

Glob patterns skipped when discovering `.gsql` and `.md` files.

Graphene Cloud URL (path selects the repo). Enables login, export, token, evals, and reviews.

Set to `false` to opt out. GRAPHENE_NO_UPDATE_NOTIFIER=1 also disables update notices.

Requires Node.js 20+. Most commands load project config from the current directory; install-browser is the exception.export, evals, and reviews talk to Graphene Cloud, not local files. export writes HTML for the synced Cloud copy. evals and reviews need an admin login or admin GRAPHENE_TOKEN.The software is licensed under the Elastic License 2.0 for internal use. Distro packages named `graphene` are often unrelated (for example the GraphQL Python library).

Graphene is developed by Graphene Systems Inc. The CLI is published on npm as `@graphenedata/cli` with the `graphene` binary. Graphene SQL is inspired by Malloy, expressed as SQL with modeled joins and measures.

npm(1), duckdb(1), dbt(1), postgres(1)

Documentation · Homepage · Source code