CLI troubleshooting

For: developers.

Most CLI issues fall into three buckets: the symlink isn't in your PATH, macOS is running the app from an unexpected location (App Translocation), or detection doesn't match what you expect.

command not found: qdeck

The symlink either wasn't installed or isn't in your shell's PATH.

Reinstall the symlink

Open QueryDeck. From the menu bar, choose QueryDeck → Settings → Tools → Install CLI. The button creates the symlink.

If the button fails, the underlying command is:

sudo ln -s /Applications/QueryDeck.app/Contents/MacOS/qdeck /usr/local/bin/qdeck

You may be prompted for your admin password the first time.

Check PATH

/usr/local/bin is in the default macOS PATH. If you've customized your shell, make sure it's still there:

echo $PATH | tr ':' '\n' | grep -F /usr/local/bin

If nothing prints, your PATH is non-standard. Add this to your ~/.zshrc or ~/.bash_profile:

export PATH="/usr/local/bin:$PATH"

Restart your terminal.

Verify the symlink

ls -l /usr/local/bin/qdeck

Expected output:

/usr/local/bin/qdeck -> /Applications/QueryDeck.app/Contents/MacOS/qdeck

If the target is wrong or the file doesn't exist, run qdeck --install-cli from inside the app (or use Settings → Tools).

"QueryDeck app not found" or App Translocation

App Translocation is a macOS security feature. The first time you open an app downloaded from the internet, macOS runs it from a sealed read-only path like /private/var/folders/... instead of /Applications. The symlink we create points at /Applications/QueryDeck.app, which doesn't have the running app.

How to tell

If qdeck reports "app not found" or "socket not reachable" right after the first launch, you're likely hitting translocation.

Fix

1. Quit QueryDeck (if open).
2. Open Finder, drag QueryDeck.app out of Applications, then back into Applications. This breaks translocation.
3. Open QueryDeck. The app now runs from /Applications/QueryDeck.app.
4. Run qdeck --install-cli again to make sure the symlink is correct.

Once you've broken translocation once, future launches and updates are fine.

"App not installed or not reachable"

qdeck couldn't reach the QueryDeck app over the local socket. Possible causes:

1. App isn't running — qdeck will launch it for you. Give it a second and try again.
2. App is running but the socket is stale — quit QueryDeck (Cmd+Q or right-click the dock icon), then run qdeck again.
3. Socket path is unwritable — check the permissions on ~/Library/Application Support/QueryDeck/. The directory should be readable and writable by your user.

Check the app is reachable:

ls -la ~/Library/Application\ Support/QueryDeck/cli.sock

If the file exists but qdeck still can't connect, force-quit QueryDeck and reopen.

Detection finds the wrong database

qdeck matched the wrong ORM, or read the wrong .env file.

Diagnose

Run with --verbose --dry-run:

qdeck --verbose --dry-run

The output shows:

• Which project root was detected
• Which detectors ran and which one matched
• Which config file was parsed
• Which env file(s) supplied which variables
• The final connection details (password redacted)

Common fixes

• Wrong environment — NODE_ENV / RAILS_ENV / DJANGO_SETTINGS_MODULE controls which environment block is read for Knex, Sequelize, Rails, Django. Set the right env before running:

  NODE_ENV=production qdeck

• Wrong project root — if you have a monorepo, qdeck might walk up too far. Run it from the right subfolder, or pass the path explicitly:

  qdeck ./apps/api

• .env.local overrides — qdeck reads .env.local after .env, so values in .env.local win. If you don't want that, rename or remove the file.

• Bypass detection — pass the URL directly:

  qdeck "postgres://user:pass@host:5432/db"

  Quote the URL to protect special characters in the password.

Detection finds no database

qdeck reports "no database config found".

Possible causes

• No supported ORM — your project uses an ORM we don't detect yet (e.g., Eloquent, MikroORM). Use a direct URL or set up a .env with DATABASE_URL.
• Env variable not exported — the ORM config references process.env.DATABASE_URL but .env is missing or doesn't have that variable. Run qdeck --verbose to see which variable wasn't resolved.
• You're in the wrong folder — qdeck walks up until it finds a project marker (.git, package.json, etc.). If you're outside any project, it has nothing to scan.

Fallback

Pass a direct URL or path:

qdeck postgres://user:pass@host/db
qdeck ./data.sqlite

License blocks the CLI

If qdeck exits with code 5, your trial has expired or no license is active.

The CLI is a paid feature. During the 14-day trial it works freely. After that, you need an active license. See Activate your license.

Getting more help

Open QueryDeck, click the feedback button in the top-right of the toolbar, and describe the issue. Include the output of:

qdeck --verbose --dry-run > qdeck-output.txt 2>&1

We'll get back to you.

What's next

• CLI overview for the conceptual model
• Commands and flags for the full reference
• ORM detection details