DataSpring CLI

Query metrics and manage dashboards from the terminal.

Installation

Using uv (Recommended)

# Install from local build
uv tool install ./backend

# Or install from GitHub (once published)
uv tool install git+https://github.com/dataspring/dataspring#subdirectory=backend

Using pip

pip install ./backend

Quick Start

# Login with Google OAuth
dataspring login

# Check who you're logged in as
dataspring whoami

# List available metrics
dataspring metrics list

# Query metrics
dataspring query -m total_revenue -g month --limit 5

# Get visualization suggestions
dataspring query -m total_revenue -g month --suggest-viz

# Export to JSON
dataspring query -m total_revenue --format json > data.json

Commands

Authentication

dataspring auth login     # Device flow: approve the code in a browser signed in to DataSpring
dataspring whoami --json  # The person, the org, where the org came from (org_from), the role
dataspring auth logout    # Revoke this machine's keys and forget them
dataspring org list       # List your organizations

Every command names its organization: --org <org>, else DATASPRING_ORG then FORSPRING_ORG, else .forspring.json ({"org": "<org>"}) in this directory or a parent, else DATASPRING_API_KEY's own org, else the only stored key; otherwise it is refused with org_required (exit 2).

Querying Metrics

# List available metrics
dataspring metrics list
dataspring metrics list --format json

# Get metric details
dataspring metrics show total_revenue

# Query data
dataspring query -m revenue -g month                    # Monthly revenue
dataspring query -m revenue -d region --limit 10        # By region
dataspring query -m revenue -m orders -g week           # Multiple metrics
dataspring query -m revenue --start 2024-01-01 --end 2024-12-31

# With visualization suggestion
dataspring query -m revenue -g month --suggest-viz

# List dimensions
dataspring dimensions list

Dashboard Management

# List dashboards
dataspring dashboards list

# Show dashboard details
dataspring dashboards show DASHBOARD_ID

# Create a new dashboard
dataspring dashboards create "My Dashboard"
dataspring dashboards create "Team Metrics" -v org  # Visible to team

# Delete a dashboard
dataspring dashboards delete DASHBOARD_ID
dataspring dashboards delete DASHBOARD_ID --yes     # Skip confirmation

Manifest Management (Admin Only)

# View manifest status
dataspring manifest status

# Export manifest
dataspring manifest export -o manifest.yaml

# Import manifest
dataspring manifest upload manifest.yaml
dataspring manifest upload manifest.yaml --force  # Overwrite conflicts

# Semantic models
dataspring models list
dataspring models show orders
dataspring models create model.yaml
dataspring models update orders updated.yaml
dataspring models delete orders

# Metrics
dataspring metrics create metric.yaml
dataspring metrics update total_revenue updated.yaml
dataspring metrics delete total_revenue
dataspring metrics preview metric.yaml  # Test before saving

Output Formats

All commands support --format:

dataspring metrics list --format json | jq '.[0]'
dataspring dashboards show abc123 --format yaml > dashboard.yaml

Configuration

Credentials are stored in ~/.dataspring/:

~/.dataspring/
├── credentials.json    # OAuth tokens (encrypted)
└── config.json         # User preferences

Development

# Build the wheel
cd backend
uv build

# Install locally for testing
uv tool install dist/dataspring_cli-*.whl --force

# Run tests
uv run pytest tests/ -v

Environment Variables