Metadata-Version: 2.5
Name: dataspring-cli
Version: 0.3.0
Summary: DataSpring CLI - Query metrics and manage dashboards from the terminal
Project-URL: Homepage, https://dataspring.app
Project-URL: Documentation, https://dataspring.app/docs
Author-email: DataSpring <support@dataspring.app>
License: Proprietary
Keywords: analytics,bi,dashboard,dbt,metricflow,metrics
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.12
Requires-Dist: google-auth-oauthlib>=1.4.1
Requires-Dist: google-auth>=2.57.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.15.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.27.1
Description-Content-Type: text/markdown

# DataSpring CLI

Query metrics and manage dashboards from the terminal.

## Installation

### Using uv (Recommended)

```bash
# 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

```bash
pip install ./backend
```

## Quick Start

```bash
# 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

```bash
dataspring login          # Login via Google OAuth (opens browser)
dataspring whoami         # Show current user and organization
dataspring logout         # Clear stored credentials
dataspring org list       # List your organizations
dataspring org switch ID  # Switch to a different organization
```

### Querying Metrics

```bash
# 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

```bash
# 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)

```bash
# 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`:

| Format | Description |
|--------|-------------|
| `table` | Human-readable ASCII table (default) |
| `json` | JSON output for scripting |
| `yaml` | YAML output for config editing |

```bash
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

```bash
# 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

| Variable | Description |
|----------|-------------|
| `FIRESTORE_EMULATOR_HOST` | Use Firestore emulator |
| `FIREBASE_AUTH_EMULATOR_HOST` | Use Auth emulator |
| `ENV` | Environment: `production`, `development`, `test` |
