Getting Started

Get up and running with Dinobase in under 5 minutes.

Install

Script (recommended)

curl -fsSL https://dinobase.ai/install.sh | bash

uv

uv tool install dinobase

pip

pip install dinobase

pipx

pipx install dinobase

Requires Python 3.10+.

Initialize

dinobase init

This creates ~/.dinobase/ with a config file and DuckDB database.

Cloud storage

Store data in S3, GCS, or Azure instead of local disk:

dinobase init --storage s3://my-bucket/dinobase/

See the Cloud Storage Backend guide for full setup.

Tip

Set DINOBASE_DIR to use a custom location:

export DINOBASE_DIR=/path/to/my/dinobase

Connect a source

File sources (instant)

The fastest way to start — no sync, no API keys:

dinobase add parquet --path ./data/events/ --name analytics
dinobase add csv --path ./exports/customers.csv --name customers

SaaS APIs

Connect with an API key:

dinobase add stripe --api-key sk_live_...
dinobase add hubspot --api-key pat-na1-...
dinobase sync

Or connect via OAuth (browser-based authorization):

dinobase auth hubspot
dinobase auth salesforce
dinobase sync

Databases

dinobase add postgres --connection-string postgresql://user:pass@host/db
dinobase sync

Note

If you skip CLI flags, Dinobase checks environment variables then prompts interactively.

See all available sources

dinobase sources --available --pretty

Lists all 100+ supported sources grouped by category (SaaS APIs, databases, cloud storage, files). See Connecting Sources for full details and Sources Reference for the complete list.

Explore your data

# What sources are connected?
dinobase status --pretty

# Inspect a table's columns and types
dinobase describe stripe.customers --pretty

Example describe output:

stripe.customers (180 rows)

  id          VARCHAR   -- Unique identifier for the object.
  email       VARCHAR   -- The customer's email address.
                          Can be null
  created     INTEGER   -- Time at which the object was created.
                          Unix timestamp. Use to_timestamp() to convert.
  delinquent  BOOLEAN   -- Whether the customer has an overdue invoice.

Column descriptions come from source APIs — Stripe’s OpenAPI spec, HubSpot’s Properties API, Postgres column comments. See Schema Annotations for how to add your own.

Run a query

dinobase query "SELECT COUNT(*) FROM stripe.customers" --pretty

Cross-source join:

dinobase query "
  SELECT s.email, s.name, h.company, d.amount
  FROM stripe.customers s
  JOIN hubspot.contacts h ON s.email = h.email
  JOIN hubspot.deals d ON h.id = d.contact_id
  WHERE d.dealstage = 'closedwon'
  ORDER BY d.amount DESC
  LIMIT 10
" --pretty

All queries use DuckDB SQL syntax. Tables are referenced as schema.table. See Querying Data for more SQL patterns and join strategies.

Set up an agent

Dinobase works with any AI agent. One command installs the MCP config for your client:

Claude Code

dinobase install claude-code

Or use the CLI directly — no configuration needed:

dinobase info          # what data is available
dinobase describe X    # column details
dinobase query "..."   # execute SQL

See the Claude Code integration guide for full details.

Claude Desktop

dinobase install claude-desktop

Writes the config to your Claude Desktop config file automatically. See the Claude Desktop integration guide.

Cursor

dinobase install cursor

Writes .cursor/mcp.json in your project root. See the Cursor integration guide.

OpenClaw

openclaw skills install dinobase

See the OpenClaw integration guide.

Other agents

Dinobase integrates with many AI frameworks. See the full list of integrations.

Keep data fresh

Set freshness thresholds and sync intervals per source:

dinobase add stripe --api-key ... --freshness 30m --sync-interval 15m

Run a background sync daemon:

dinobase sync --schedule --interval 30m

Or sync alongside the MCP server:

dinobase serve --sync --sync-interval 30m

See Syncing & Scheduling for freshness thresholds, live fetch, and scheduled sync details.

Try with sample data

Generate realistic test data without any API keys:

pip install faker
python scripts/generate_sample_data.py
dinobase init
dinobase add parquet --path sample_data/ --name demo
dinobase query "SELECT COUNT(*) FROM demo.customers" --pretty

Next steps

• Connecting Sources — all source types in detail
• Querying Data — SQL patterns, joins, aggregations
• Syncing & Scheduling — freshness, live fetch, daemon mode
• Schema Annotations — add context for AI agents
• Mutations — write data back to source APIs
• MCP Integration — how the MCP server works
• Sources Reference — full list of 100+ sources
• CLI Reference — all commands and flags