Getting Started

This guide gets one source working from the CLI. OneQuery keeps credentials server-side; callers use source identifiers like postgres://warehouse.

Prerequisites

Choose one install method. You only need the requirement for that method.

Install method	Requirement
npm or npx	Node.js 22+
Bun or bunx	Bun; Node.js 22+ if you run a local gateway
Homebrew	Homebrew
Install script	curl and tar; the script manages Node.js runtime

For source setup, have a OneQuery server URL or local gateway, plus a read-only credential or limited provider token.

Install the CLI

npm

npm install -g @onequery/cli

Homebrew

brew install wordbricks/tap/onequery

Bun

bun add -g @onequery/cli

Script

curl -fsSL https://onequery.dev/install.sh | sh

You can also run the CLI without a global install:

npx @onequery/cli --help

Choose a Server

Use a shared server URL if your team provides one:

onequery config set api.server_url https://onequery.example.com

Start a gateway only when you run OneQuery yourself:

onequery gateway start

First Run

1. Verify and log in.

   onequery --version
   onequery auth login
   onequery auth whoami

2. Connect a source.

   Replace the placeholders with read-only PostgreSQL credentials.

   onequery source connect --source postgres \
     --input '{"sourceKey":"warehouse","credentials":{"host":"db.example.com","port":5432,"database":"app","username":"onequery_readonly","password":"<read-only-password>","sslMode":"require"}}'

3. Run a smoke query.

   onequery query exec --source postgres://warehouse --sql "select 1"

4. Confirm the source.

   onequery source list

You are done when:

• onequery auth whoami shows the expected user and organization.
• onequery source list shows the source you connected.
• The smoke query returns one row.

What to Read Next

• Source identifiers explains postgres://warehouse and other source URI shapes.
• Run a query covers read-only query execution.
• Agent workflows shows how to expose OneQuery to coding agents and automation.