Skip to main content
Running datafrey with no subcommand runs datafrey login.

​
Global flags

FlagDescription
--version, -vPrint the installed version and exit
--helpShow help for any command

​
datafrey login

Authenticate via browser and continue into database connection. 
datafrey login [OPTIONS]
OptionDescription
--no-browserDon’t open the browser automatically — print the device code URL instead
What it does:
  1. Runs the OAuth device flow (WorkOS). Opens a browser by default.
  2. Stores access and refresh tokens in your OS keyring.
  3. Calls datafrey db connect to connect a database.
If you’re already logged in, login asks whether to re-authenticate.

​
datafrey logout

Remove stored credentials from the keyring. 
datafrey logout
Local-only — does not affect database connections stored on the server.

​
datafrey status

Show authentication, database, and index status. If indexing is in progress, the output streams live until it completes. 
datafrey status [OPTIONS]
OptionDescription
--jsonOutput as JSON
The output includes your account, the connected database (name, host, status), and the index state (last synced, tables, columns, in-progress flag).

​
datafrey db

Manage your database connection. DataFrey supports one database per account.

​
datafrey db connect

Connect a database interactively. 
datafrey db connect
Walks you through:
  1. Provider selection (currently Snowflake).
  2. Auth method (PAT).
  3. Database and warehouse names.
  4. Setup SQL — generated with your values, shown for you to run in Snowflake.
  5. Credential collection and client-side encryption.
  6. Connection test (async).
  7. On success, offers to build the index.
  8. On success, runs the interactive client setup menu.
Requires recent authentication (within 5 minutes). If your session is older, the CLI re-authenticates first. Fails if a database is already connected — run datafrey db drop first.

​
datafrey db list

List the connected database and its status. 
datafrey db list [OPTIONS]
OptionDescription
--jsonOutput as JSON
Statuses:
StatusMeaning
connectedConnection verified successfully
loadingConnection test in progress
errorConnection test failed — check credentials

​
datafrey db drop

Remove the connected database. 
datafrey db drop [OPTIONS]
OptionDescription
--yes, -ySkip the confirmation prompt
Deletes the connection record, credentials, and the associated index from the server.

​
datafrey index

Manage the database schema index used by the plan tool.

​
datafrey index

Sync the index. With no subcommand, datafrey index triggers a rebuild. 
datafrey index
Runs server-side. The CLI returns immediately — use datafrey status to check progress. Run this after onboarding and whenever your schema changes. Planning is unavailable until the index is built. See Planning for details.

​
datafrey index drop

Drop the schema index (hard reset). 
datafrey index drop [OPTIONS]
OptionDescription
--yes, -ySkip the confirmation prompt
Planning stops working until you rebuild with datafrey index. Use this if you want to opt out of indexing entirely — see Security — Controls for sensitive data.

​
datafrey client

Configure an AI client to use DataFrey. 
datafrey client              # interactive menu
datafrey client claude       # Claude Code directly
datafrey client cursor       # Cursor directly
datafrey client mcp          # print MCP config block
Supported clients:
  • Claude Code — runs claude plugin marketplace add datafrey-ai/datafrey followed by claude plugin install datafrey@datafrey.
  • Cursor — opens a cursor:// install deeplink that registers the DataFrey MCP server.
  • MCP (Custom) — prints the JSON config block and copies it to your clipboard for manual paste.
Safe to re-run.

​
datafrey doctor

Diagnose your environment. 
datafrey doctor
Checks:
  • Python version (≥3.13).
  • CLI version.
  • OS keyring backend availability.
  • Authentication state.
  • Number of connected databases.
  • If auth fails: API reachability via DATAFREY_API_URL.
Exits non-zero if any check fails.

​
Environment variables

VariableDescription
DATAFREY_API_URLOverride the API base URL. Default: https://api.datafrey.ai/manage/v1. Use with a local or staging instance.
DATAFREY_TOKENProvide an access token directly, bypassing keyring lookup. Useful in CI or scripted environments.
Example — use a local dev server: 
DATAFREY_API_URL=http://localhost:8000/manage/v1 datafrey status
Example — CI pipeline with a service account token: 
DATAFREY_TOKEN=$MY_TOKEN datafrey db list --json