Documentation Index

Fetch the complete documentation index at: https://docs.dovetail.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Dovetail CLI

​

What can you do with the Dovetail CLI?

• Bulk import from 9+ sources — Notion, Confluence, Google Drive, Airtable, Marvin, Condens, EnjoyHQ, Productboard, and local files
• Preserve formatting and metadata — Headings, lists, tables, code blocks, attachments, author info, dates, and tags come through intact
• Preview before committing — See exactly what will be imported before data touches your workspace
• Resume interrupted imports — If an import fails partway through, pick up where you left off—no re-processing needed
• Batch multiple sources — Configure migrations from Notion and Confluence in one config file, run them together
• Filter and limit — Import only records matching specific titles, dates, or file types
• Test connections — Validate API credentials and workspace permissions before running the full migration

​

Security and permissions

​

Prerequisites

• A Dovetail workspace and an API key. Generate one in your workspace settings.
• What plans support the CLI?
  • All plans except plans that have HIIPA enabled.
• Your workspace URL — for example, https://yourcompany.dovetail.com.
• One of the supported install paths:
  • npm install: Node.js and npm. 
• Build from source: Go 1.25 or later, plus make.
• The credentials for each source you plan to import from. These vary by source — see Authenticate below.

​

Install

​

Install via npm

npm install -g @heydovetail/dt

dt --version

​

Build from source

git clone https://github.com/dovetail/cli.git
cd cli
make install

export PATH="$HOME/.local/bin:$PATH"

• make build — compile the binary without installing it.
• make test — run the test suite.
• make lint — run golangci-lint.

​

Install shell completions

dt completions install

​

Authenticate

​

Authenticate to Dovetail

export DOVETAIL_API_KEY="your-api-key"
dt init

1. Confirms your workspace URL (for example, https://yourcompany.dovetail.com).
2. Stores your API key.
3. Walks you through adding your first source.

​

Authenticate each source

​

Supported sources & field mapping

​

Notion

• Pages and database entries with all formatting (headings, lists, tables, code blocks, callouts, toggles)
• Inline attachments and cover images
• Metadata: author, creation date, last-modified date, tags, properties
• Child pages (up to 3 levels of nesting, configurable)

• Notion Integration created at https://www.notion.so/my-integrations
• All databases you want to migrate must be explicitly shared with the integration
• Integration must have “Read” permissions at minimum

export NOTION_TOKEN="ntn_xxxxxxxxxxxx"
dt source add notion
dt source validate notion

​

Confluence

• Cloud pages and blog posts with full HTML content and formatting
• Attachments (PDFs, images, Word docs, etc.)
• Labels and metadata (author, creation/modification dates, space key)
• Parent-child page relationships preserved
• Comments (available as metadata)

• Confluence Cloud workspace (Server/Data Center not supported)
• Atlassian API token from https://id.atlassian.com/manage-profile/security/api-tokens
• Your Confluence base URL (e.g., https://mycompany.atlassian.net/wiki)
• Account email address
• Permission to access the spaces you’re migrating (typically Editor or Admin)

export CONFLUENCE_API_TOKEN="your-api-token"
export CONFLUENCE_EMAIL="you@company.com"
export CONFLUENCE_BASE_URL="https://mycompany.atlassian.net/wiki"
dt source add confluence
dt source validate confluence

• 300 requests per minute per API token (Atlassian limit)
• The CLI automatically retries with exponential backoff; no action needed

​

Google Drive

• Google Docs (exported as HTML with formatting)
• Google Sheets (optionally, as CSV)
• PDFs, images, and other files (as attachments)
• Folder structure and hierarchy preserved
• File metadata (owner, creation/modification dates)

1. OAuth (personal/shared drives, recommended for most users)

• Google Cloud project with Drive API enabled
• OAuth 2.0 Desktop client ID created
• dt source add gdrive opens your browser to sign in
• No credential file needed; token is stored securely

2. Service account (org/shared drives)

• Service account created in Google Cloud
• JSON key file downloaded
• Drive folder explicitly shared with the service account email
• Set GOOGLE_APPLICATION_CREDENTIALS environment variable

# OAuth (most common)
dt source add gdrive
dt source validate gdrive

# Service account (shared drives)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
dt source add gdrive
dt source validate gdrive

• 10 million read requests per day (per project)
• 600 requests per minute per user
• The CLI automatically retries rate-limited requests

• Large files (>50 MB) may take longer to transfer; no timeout
• Empty files are skipped
• Google Sheets are converted to CSV format

​

Airtable

• Records from all tables/views
• All field values (text, numbers, attachments, linked records, etc.)
• Attachment files uploaded as Dovetail attachments
• Linked record metadata (record name, ID)
• Field names and types preserved

• Airtable personal access token from https://airtable.com/create/tokens
• Required scopes: data.records:read and schema.bases:read
• Read access to the base(s) you’re migrating

export AIRTABLE_TOKEN="your-token"
dt source add airtable
dt source validate airtable

• 5 requests per second (Airtable limit)
• The CLI respects this automatically; no backoff needed

• Linked records are imported as metadata; you can later link them in Dovetail
• Attachment metadata is preserved (file name, size, URL)

​

Marvin

• Video/audio recordings → uploaded as data with automatic transcription
• Insights (reports) → imported as docs with markdown content
• Interview metadata (date, duration, tags, participant info)

• Manual export from Marvin (no public API), or use Claude Code /marvin-download skill
• Folder structure:

marvin-export/
  Project Name/
    files/
      Interview 1.mp4
      Interview 2.mp4
    insights/
      My Report/
        content.md
        metadata.json

# In Claude Code, run: /marvin-download
# Downloads all recordings and insights automatically
# Then configure the CLI:
dt source add marvin
dt migrate run --source marvin --preview

1. In Marvin, go to each project → All Actions → Download Video
2. Copy insight markdown into content.md files in the folder structure above
3. Run:

dt source add marvin

• Video/audio files are uploaded as attachments; Dovetail generates transcripts automatically
• Transcription typically completes within 10 minutes for 1-hour recordings
• Insights are imported as plain markdown docs; no special formatting required
• Maximum file size: 5 GB per recording

​

Condens

• Sessions (interview notes, transcripts, video) → data records
• Artifacts (reports, deliverables) → docs
• Video attachments automatically included
• Session metadata (date, participants, tags)

• Condens export ZIP file from Project → Settings → Export data
• No API credentials needed

dt source add condens
# When prompted, provide the path to your .zip file
dt migrate run --source condens --preview
dt migrate run --source condens

• ZIP is processed locally; never uploaded to Dovetail servers
• Large projects (>1 GB) may take 5–10 minutes to process
• Video formats supported: MP4, WebM, MOV (same as Dovetail)

​

EnjoyHQ

• Stories (customer feedback) with HTML content → data records
• Projects (plans + summaries) → docs
• Documents (feedback text) → data records
• Labels, state, customer info preserved

• EnjoyHQ API token from workspace settings
• Read access to stories, projects, and documents

export ENJOYHQ_API_TOKEN="your-token"
dt source add enjoyhq
dt source validate enjoyhq
dt migrate run --source enjoyhq --preview

• 100 requests per minute
• The CLI automatically respects this limit

​

Productboard

• Notes (customer feedback, research) → data records
• Features (with descriptions, metadata) → docs
• Linked data (initiatives, objectives)
• Metadata (date, priority, status, owner)

• Productboard API token from Settings → Integrations → Public API
• Read access to notes and features

export PRODUCTBOARD_API_TOKEN="your-token"
dt source add productboard
dt source validate productboard
dt migrate run --source productboard --preview

• 60 requests per minute (Productboard public API)
• The CLI automatically queues and retries

​

Local files

• Markdown (.md) → record body
• Text files (.txt, .html) → record body
• PDFs, images, videos, Word docs → attachments
• Folder structure preserved

• Local folder with files you want to import
• No credentials needed

dt source add local
# When prompted, provide the path to your folder
dt migrate run --source local --preview
dt migrate run --source local

extensions: ".md,.pdf,.mp4"  # Import only these file types (optional)

• File permissions: must have read access
• Symlinks are followed
• Hidden files (starting with .) are skipped
• Maximum file size: 5 GB

​

Configuration

​

Configuration file structure (dt.yaml)

dovetail:
  base_url: "https://mycompany.dovetail.com"
  api_key: "${DOVETAIL_API_KEY}"  # Or paste key directly (not recommended)

sources:
  notion:
    token: "${NOTION_TOKEN}"
    child_pages: "true"

  confluence:
    base_url: "https://mycompany.atlassian.net/wiki"
    email: "you@company.com"
    token: "${CONFLUENCE_API_TOKEN}"

migrations:
  # Notion database to project data
  - source: notion
    content:
      - "notion-database-id-here"
    destination:
      type: "data"
      parent:
        type: "project"
        name: "Customer Research"

  # Confluence space to project docs
  - source: confluence
    content:
      - "PROD"  # Space key
    destination:
      type: "doc"
      parent:
        type: "project"
        name: "Product Knowledge Base"

  # Google Drive folder to data
  - source: gdrive
    content:
      - "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs"  # Folder ID
    destination:
      type: "data"
      parent:
        type: "project"
        name: "UX Research Archive"
    options:
      recursive: "true"
      include_binary: "true"

  # Local files to data
  - source: local
    content:
      - "/path/to/your/folder"
    destination:
      type: "data"
      parent:
        type: "project"
        name: "Research Files"
    options:
      extensions: ".md,.pdf,.mp4"

​

Configuration resolution order

1. CLI flags — dt migrate run --source notion --limit 100
2. Environment variables — export NOTION_TOKEN="..."
3. dt.yaml file — sources.notion.token
4. Defaults — Built-in sensible defaults

​

Environment variables reference

​

Running migrations

​

Preview before importing

dt migrate run --source notion --preview

• Number of records that will be imported
• Size of attachments
• Any records that will be skipped (and why)
• Estimated import time

​

Run the migration

dt migrate run --source notion

1. Fetch records from the source
2. Transform them into Dovetail format
3. Upload in batches with progress updates
4. Show a summary of imported records and any errors

​

Advanced migration options

# Run migrations for multiple sources at once
dt migrate run

# Run only specific migrations by source
dt migrate run --source notion
dt migrate run --source confluence

# Limit the number of records processed (useful for testing)
dt migrate run --source notion --limit 10

# Filter by title or date
dt migrate run --source notion --filter "title:Interview"
dt migrate run --source notion --filter "date:2024-01-01:2024-12-31"

# Dry-run: fetch and transform, but don't upload
dt migrate run --source notion --dry-run

# Re-run without creating duplicates (uses record IDs for deduplication)
dt migrate run --source notion --upsert

# Minimal output (errors and summary only)
dt migrate run --source notion --quiet

# Detailed progress logs
dt migrate run --source notion --verbose

# Machine-readable JSON output
dt migrate run --source notion --output json

# Use a specific config file
dt migrate run --config /path/to/custom-dt.yaml

# Resume an interrupted migration
dt migrate resume

​

Duplicate handling & upsert behavior

dt migrate run --source notion --upsert

• Records are matched by source ID (Notion page ID, Confluence page ID, etc.)
• If a record with the same source ID exists in Dovetail, it’s updated (not duplicated)
• New records are created if they don’t exist
• The upsert feature works with all sources except local files
  Important: If you delete a record in Dovetail, running —upsert again will re-create it from the source.

​

Testing & validation

​

Validate a source connection

dt source validate notion

• API token is valid and not expired
• Token has necessary permissions
• You have access to at least one database/page
• Network connectivity to the source API

​

Validate migration configuration

dt migrate validate

​

Workspace health check

dt status

• Workspace name and URL
• Number of projects, docs, records
• Configured migrations
• Any incomplete or failed imports

​

Workspace statistics

dt stats

​

Diagnostic check

dt doctor

• Configuration file validity
• Dovetail API connectivity
• Source credentials
• Staging directory available
• Disk space

​

Troubleshooting

dt migrate run --verbose

dt migrate status --output json

​

Uninstall

​

If you installed via npm

npm uninstall -g @heydovetail/dt

​

If you built from source

rm ~/.local/bin/dt

​

Clean up configuration and staging

• Delete your config file (dt.yaml in whichever directories you ran the CLI from).
• Run dt clean before uninstalling to remove staging directories. After uninstall, remove any remaining staging directories manually.
• Unset the environment variables you exported (DOVETAIL_API_KEY, NOTION_TOKEN, and so on) from your shell profile.

​

Revoke credentials

• Delete your Dovetail API key in your workspace settings.
• Revoke each source token from the source’s own settings (Notion integrations page, Atlassian API tokens, Airtable tokens page, Productboard public API, and so on).
• For Google Drive OAuth, revoke access at myaccount.google.com/permissions. For service accounts, delete the JSON key from your Google Cloud project.