Skip to content

getting-started.md

Latest commit

 

History

History
256 lines (177 loc) · 6.08 KB

getting-started.md

File metadata and controls

256 lines (177 loc) · 6.08 KB
Raw

Getting Started

Get up and running with Dinobase in under 5 minutes.

Install

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.

Tip (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

Add a connector

File connectors (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

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.

MCP servers

Connect any MCP server as a connector. Dinobase discovers the server's read-only tools and syncs their output as SQL tables:

# stdio (local process)
dinobase connector create posthog_mcp \
  --transport stdio \
  --command "npx -y @posthog/mcp-server"
dinobase sync posthog_mcp

# SSE or streamable HTTP
dinobase connector create my_server \
  --transport sse \
  --url "https://server/sse"

After syncing, query the data like any other connector:

dinobase query "SELECT * FROM posthog_mcp.list_projects LIMIT 10"

To call tools directly (for writes or tools with required arguments):

dinobase mcp call posthog_mcp.dashboard-get '{"id": 1118504}'

See MCP Server Connectors for full details.

See all available connectors

dinobase connectors --available --pretty

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

Explore your data

# What connectors are configured?
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 upstream 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-connector 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 connector:

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