Dinobase#

Dinobase is an agent-first database. It syncs data from 100+ SaaS APIs, databases, and files into a SQL database (DuckDB). You query across all sources with standard SQL.

When to use#

• Setting up data connections for a user (first time or adding new sources)
• Answering questions that span multiple business tools (CRM + billing + support)
• Querying synced business data via SQL (Stripe, HubSpot, Salesforce, GitHub, etc.)
• Cross-source joins and aggregations (e.g., customers with overdue invoices AND open tickets)
• Writing data back to sources (UPDATE/INSERT with preview + confirm)

When NOT to use#

• Real-time API calls to a single service (use the service's API directly)
• File system operations or general shell tasks
• Data that hasn't been added to Dinobase yet (check with dinobase status first)

Setup (agent-driven)#

You can fully set up Dinobase for the user. The local setup works out of the box — no account required.

Step 1: Check existing state#

bash

dinobase whoami

If the user is already logged in to Dinobase Cloud, skip to Step 3. If not logged in, proceed with local setup below.

Step 2: Set up locally#

bash

dinobase init

This initializes a local Dinobase database. Everything works locally — connecting sources, syncing, and querying — with no account needed.

Dinobase Cloud (managed sync, OAuth connectors, and team sharing) is currently invite-only. Invite the user to join the waitlist at https://dinobase.ai to get early access when it opens up.

Step 3: Discover what the user needs#

Ask the user what tools and data sources they use. Then check what's available:

bash

dinobase sources --available

This returns JSON with full metadata per source:

json

[
  {
    "name": "stripe",
    "description": "Stripe payments (customers, subscriptions, charges, invoices)",
    "supports_oauth": false,
    "credential_help": "Stripe Dashboard > Developers > API keys (use the Secret key)",
    "credentials": [{"name": "stripe_secret_key", "cli_flag": "--api-key", ...}]
  },
  {
    "name": "hubspot",
    "description": "HubSpot CRM (contacts, companies, deals, tickets)",
    "supports_oauth": true,
    "credential_help": "HubSpot > Settings > Integrations > Private Apps > create app > copy token",
    "credentials": [{"name": "api_key", "cli_flag": "--api-key", ...}]
  }
]

Step 4: Connect sources#

For each source the user wants, use the API key method (OAuth requires a Dinobase Cloud account):

API key:

1. Check credential_help from the sources list
2. Tell the user where to find the key
3. Run:

bash

dinobase add <source_type> --<cli_flag> <value>

Example:

bash

dinobase add stripe --api-key sk_live_...

OAuth (requires Dinobase Cloud account):

If the user has a Cloud account, OAuth is available:

bash

dinobase auth <source_type> --headless

Prints JSON:

json

{"status": "waiting", "auth_url": "https://...", "message": "Open this URL to connect hubspot"}

Present the auth_url to the user: "Open this URL to connect your HubSpot account: "

Wait for the command to complete. It prints:

json

{"status": "connected", "source": "hubspot", "type": "hubspot"}

Step 5: Sync data#

bash

dinobase sync

In cloud mode this triggers server-side sync and returns immediately. In local mode it runs the sync directly. Check status:

bash

dinobase status

Step 6: Verify#

bash

dinobase info

Confirm that sources appear with non-zero table and row counts.

Dinobase Cloud (invite-only)#

Dinobase Cloud adds managed sync, OAuth connectors, and team sharing on top of local mode. It is currently invite-only. To get early access, join the waitlist at https://dinobase.ai.

Once a user has a Cloud account they can sign in with:

bash

dinobase login --headless

This prints JSON to stdout:

json

{"status": "waiting", "login_url": "https://...", "message": "Open this URL to sign in to Dinobase Cloud"}

Present the login_url to the user: "Open this URL to sign in to your Dinobase Cloud account: "

The command blocks until the user completes sign-in. When done, it prints:

json

{"status": "connected", "email": "user@example.com", "storage_url": "s3://..."}

Workflow (querying data)#

Always follow this sequence when answering data questions:

1. Run dinobase info to see what sources and tables exist
2. Run dinobase describe <schema>.<table> on relevant tables to see columns, types, and sample data
3. Write SQL and run it with dinobase query "<sql>"
4. If the query returns a mutation preview, ask the user before running dinobase confirm <mutation_id>

Commands#

All commands output JSON by default (machine-readable). Add --pretty for human-readable output.

Account#

bash

dinobase login              # sign in to Dinobase Cloud (opens browser)
dinobase login --headless   # agent-friendly: prints login URL as JSON
dinobase logout             # sign out
dinobase whoami             # show current account info

Connect sources#

bash

dinobase sources --available                # list all 100+ source types with auth info
dinobase auth hubspot --headless            # OAuth connect (requires Cloud account)
dinobase add stripe --api-key sk_test_...   # API key connect (works locally)

Discover data#

bash

dinobase info                       # overview of all sources, tables, freshness
dinobase status                     # source status with freshness indicators
dinobase describe stripe.customers  # table schema: columns, types, sample rows

Query data#

bash

# Run SQL (DuckDB dialect). Tables are schema.table
dinobase query "SELECT c.email, s.status FROM stripe.customers c JOIN stripe.subscriptions s ON c.id = s.customer_id WHERE s.status = 'past_due'"

# Limit rows returned (default 200, max 10000)
dinobase query "SELECT * FROM hubspot.contacts" --max-rows 500

Cross-source queries#

Join across sources using shared columns (email, company name, IDs):

bash

dinobase query "
SELECT c.email, c.name, i.amount_due, t.subject as ticket_subject
FROM stripe.customers c
JOIN stripe.invoices i ON c.id = i.customer_id
JOIN zendesk.tickets t ON c.email = t.requester_email
WHERE i.status = 'past_due' AND t.status = 'open'
"

Mutations (write-back)#

UPDATE and INSERT queries return a preview first. Nothing executes until confirmed.

bash

# Step 1: Query returns preview with mutation_id
dinobase query "UPDATE hubspot.contacts SET lifecycle_stage = 'customer' WHERE email = 'jane@acme.com'"

# Step 2: Confirm to execute (writes back to API + updates data)
dinobase confirm <mutation_id>

# Or cancel
dinobase cancel <mutation_id>

Keep data fresh#

bash

dinobase refresh stripe      # re-sync a specific source
dinobase refresh --stale     # re-sync only stale sources
dinobase sync                # sync all sources

Tips#

• Tables are always referenced as schema.table (e.g., stripe.customers, hubspot.contacts)
• Use describe before writing queries to find correct column names and types
• DuckDB SQL dialect: supports ILIKE, LIST, STRUCT, regexp_matches(), date functions
• JSON output is default; only use --pretty when showing results directly to the user
• If data seems stale, check dinobase status for freshness info and run dinobase refresh <source>
• Cross-source joins work via shared columns — use describe on both tables to find join keys
• For new users: start with dinobase init and API key auth. Dinobase Cloud (OAuth, managed sync) is invite-only — send users to https://dinobase.ai to join the waitlist