CLI overview

For: developers.

qdeck is a small command-line tool that opens QueryDeck connected to whatever database your current project uses. It does three things, in order:

1. Figure out what's in front of it (a project folder, a URL, or a SQLite file).
2. Find or parse the connection details.
3. Hand them to the QueryDeck app over a local socket, which opens a window connected to the right database.

If you're new to the CLI, start with the quickstart. This page is for once you want to understand what's going on under the hood.

Where the binary lives

The CLI binary lives inside the QueryDeck app bundle. The exact path is:

/Applications/QueryDeck.app/Contents/MacOS/qdeck

qdeck --install-cli creates a symlink at /usr/local/bin/qdeck so the command is in your PATH. The symlink points at the binary inside the bundle, so app updates automatically update the CLI too.

What gets passed to the app

When qdeck connects to the app, it sends a DetectionResult over a local Unix socket. The payload looks like:

orm:         "Prisma"               // or Drizzle, TypeORM, Knex, ...
dbType:      "postgresql"           // or mysql, sqlite
host:        "db.example.com"
port:        5432
user:        "myapp_user"
database:    "myapp_production"
password:    "<from .env or keychain>"
sslMode:     "require"
configPath:  "prisma/schema.prisma" // relative to projectRoot
environment: "production"           // detected from host: local/staging/production
projectRoot: "/Users/you/code/myapp"

The app uses configPath and projectRoot to drive Drift Mode and to associate queries you save with the right project.

Routing

qdeck <target> looks at <target> and picks one of three paths:

Project scan

When qdeck scans a folder, it does two phases:

Phase 1: ORM detectors

QueryDeck tries each of these in order until one matches:

1. Prisma — looks for schema.prisma, prisma.config.ts, prisma.config.js.
2. Drizzle — looks for drizzle.config.ts, drizzle.config.js.
3. TypeORM — looks for data-source.ts, data-source.js, ormconfig.json.
4. Knex — looks for knexfile.js, knexfile.ts, knexfile.mjs.
5. Sequelize — looks for config/config.json, .sequelizerc.
6. Django — looks for manage.py near a settings.py with a DATABASES block.
7. Rails — looks for config/database.yml.

The first detector that finds a usable config wins. If two ORMs are present in the same repo (rare but possible), the order above decides which one is used. Override the default with --verbose to see all matches and pick interactively.

Phase 2: .env fallback

If no ORM matches, qdeck reads .env, .env.local, .env.development, .env.production in order, looking for any variable that holds a database URL. The first one wins.

Recognized variable names:

• DATABASE_URL
• DB_URL
• POSTGRES_URL, POSTGRESQL_URL
• MYSQL_URL
• PG_URL, PG_CONNECTION_STRING

If none of these are found, qdeck reports "no database config found" and exits.

Project root detection

When you run qdeck deep inside a project, the scanner walks up the directory tree until it finds one of:

• .git/
• package.json
• Cargo.toml
• pyproject.toml
• Gemfile
• composer.json

Whichever it finds first becomes the project root. The scan happens from the root, so it doesn't matter what subfolder you're in when you run the command.

Exit codes

Useful in scripts where you might want to fall back to another tool if qdeck can't proceed.

What's next

• Detected ORMs for what each detector parses in detail
• Commands and flags for the full reference
• Troubleshooting for command not found, translocation, PATH issues