@bonnard/cli 0.2.7 → 0.2.9

package/dist/docs/topics/workflow.deploy.md

@@ -1,193 +0,0 @@
-# Deploy
-
-> Deploy your cubes and views to the Bonnard platform using the CLI. Once deployed, your semantic layer is queryable via the REST API, MCP for AI agents, and connected BI tools.
-
-## Overview
-
-The `bon deploy` command uploads your cubes and views to Bonnard, making them available for querying via the API. It validates and tests connections before deploying, and creates a versioned deployment with change detection.
-
-## Usage
-
-```bash
-bon deploy -m "description of changes"
-```
-
-A `-m` message is **required** — it describes what changed in this deployment.
-
-### Flags
-
-| Flag | Description |
-|------|-------------|
-| `-m "message"` | **Required.** Deployment description |
-| `--ci` | Non-interactive mode |
-
-Datasources are always synced automatically during deploy.
-
-### CI/CD
-
-For automated pipelines, use `--ci` for non-interactive mode:
-
-```bash
-bon deploy --ci -m "CI deploy"
-```
-
-## Prerequisites
-
-1. **Logged in** — run `bon login` first
-2. **Valid cubes and views** — must pass `bon validate`
-3. **Working connections** — data sources must be accessible
-
-## What Happens
-
-1. **Validates** — checks cubes and views for errors
-2. **Tests connections** — verifies data source access
-3. **Uploads** — sends cubes and views to Bonnard
-4. **Detects changes** — compares against the previous deployment
-5. **Activates** — makes cubes and views available for queries
-
-## Example Output
-
-```
-bon deploy -m "Add revenue metrics"
-
-✓ Validating...
-  ✓ bonnard/cubes/orders.yaml
-  ✓ bonnard/cubes/users.yaml
-  ✓ bonnard/views/orders_overview.yaml
-
-✓ Testing connections...
-  ✓ datasource "default" connected
-
-✓ Deploying to Bonnard...
-  Uploading 2 cubes, 1 view...
-
-✓ Deploy complete!
-
-Changes:
-  + orders.total_revenue (measure)
-  + orders.avg_order_value (measure)
-  ~ orders.count (measure) — type changed
-
-⚠ 1 breaking change detected
-```
-
-## Change Detection
-
-Every deployment is versioned. Bonnard automatically detects:
-
-- **Added** — new cubes, views, measures, dimensions
-- **Modified** — changes to type, SQL, format, description
-- **Removed** — deleted fields (flagged as breaking)
-- **Breaking changes** — removed measures/dimensions, type changes
-
-## Reviewing Deployments
-
-After deploying, use these commands to review history and changes:
-
-### List deployments
-
-```bash
-bon deployments          # Recent deployments
-bon deployments --all    # Full history
-```
-
-### View changes in a deployment
-
-```bash
-bon diff <deployment-id>              # All changes
-bon diff <deployment-id> --breaking   # Breaking changes only
-```
-
-### Annotate changes
-
-Add reasoning or context to deployment changes:
-
-```bash
-bon annotate <deployment-id> --data '{"object": "note about why this changed"}'
-```
-
-Annotations are visible in the schema catalog and help teammates understand why changes were made.
-
-## Deploy Flow
-
-```
-bon deploy -m "message"
-    │
-    ├── 1. bon validate (must pass)
-    │
-    ├── 2. Test all datasource connections (must succeed)
-    │
-    ├── 3. Upload to Bonnard API
-    │       - cubes from bonnard/cubes/
-    │       - views from bonnard/views/
-    │       - datasource configs
-    │
-    ├── 4. Detect changes vs. previous deployment
-    │
-    └── 5. Activate deployment
-```
-
-## Error Handling
-
-### Validation Errors
-
-```
-✗ Validating...
-
-bonnard/cubes/orders.yaml:15:5
-  error: Unknown measure type "counts"
-
-Deploy aborted. Fix validation errors first.
-```
-
-### Connection Errors
-
-```
-✗ Testing connections...
-  ✗ datasource "analytics": Connection refused
-
-Deploy aborted. Fix connection issues:
-  - Check credentials in .bon/datasources.yaml
-  - Verify network access to database
-  - Run: bon datasource add (to reconfigure)
-```
-
-### Auth Errors
-
-```
-✗ Not logged in.
-
-Run: bon login
-```
-
-## What Gets Deployed
-
-| Source | Deployed |
-|--------|----------|
-| `bonnard/cubes/*.yaml` | All cube definitions |
-| `bonnard/views/*.yaml` | All view definitions |
-| `.bon/datasources.yaml` | Connection configs (credentials encrypted) |
-| `bon.yaml` | Project settings |
-
-## Deployment Behavior
-
-- **Replaces** previous deployment (not additive)
-- **All or nothing** — partial deploys don't happen
-- **Instant** — changes take effect immediately
-- **Versioned** — every deployment is tracked with changes
-
-## Best Practices
-
-1. **Always include a meaningful message** — helps teammates understand what changed
-2. **Validate first** — run `bon validate` before deploy
-3. **Test locally** — verify queries work before deploying
-4. **Use version control** — commit cubes and views before deploying
-5. **Review after deploy** — use `bon diff` to check for unintended breaking changes
-6. **Annotate breaking changes** — add context so consumers know what to update
-
-## See Also
-
-- workflow
-- workflow.validate
-- cubes
-- views

package/dist/docs/topics/workflow.mcp.md

@@ -1,179 +0,0 @@
-# MCP
-
-> Connect AI agents like Claude, ChatGPT, and Cursor to your semantic layer using the Model Context Protocol. MCP gives agents governed access to your metrics and dimensions.
-
-## Overview
-
-After deploying with `bon deploy`, AI agents can query your semantic layer through the Model Context Protocol (MCP). Bonnard's MCP server provides tools for exploring your data model and running queries.
-
-MCP is supported by Claude, ChatGPT, Cursor, Windsurf, VS Code, Gemini, and more.
-
-## MCP URL
-
-```
-https://mcp.bonnard.dev/mcp
-```
-
-## Setup
-
-### Claude Desktop
-
-1. Click the **+** button in the chat input, then select **Connectors > Manage connectors**
-
-![Claude Desktop — Connectors menu in chat](/images/claude-chat-connectors.png)
-
-2. Click **Add custom connector**
-3. Enter a name (e.g. "Bonnard MCP") and the MCP URL: `https://mcp.bonnard.dev/mcp`
-4. Click **Add**
-
-![Claude Desktop — Add custom connector dialog](/images/claude-add-connector.png)
-
-Once added, enable the Bonnard connector in any chat via the **Connectors** menu.
-
-Remote MCP servers in Claude Desktop must be added through the Connectors UI, not the JSON config file.
-
-### ChatGPT
-
-Custom MCP servers must be added in the browser at [chatgpt.com](https://chatgpt.com) — the desktop app does not support this.
-
-1. Go to [chatgpt.com](https://chatgpt.com) in your browser
-2. Open **Settings > Apps**
-
-![ChatGPT — Settings > Apps](/images/chatgpt-apps.png)
-
-3. Click **Advanced settings**, enable **Developer mode**, then click **Create app**
-
-![ChatGPT — Advanced settings with Developer mode and Create app](/images/advanced-create-app-chatgpt.png)
-
-4. Enter a name (e.g. "Bonnard MCP"), the MCP URL `https://mcp.bonnard.dev/mcp`, and select **OAuth** for authentication
-5. Check the acknowledgement box and click **Create**
-
-![ChatGPT — Create new app with MCP URL](/images/chatgpt-new-app.png)
-
-Once created, the Bonnard connector appears under **Enabled apps**:
-
-![ChatGPT — Bonnard MCP available in chat](/images/chatgpt-chat-apps.png)
-
-Available on Pro and Plus plans.
-
-### Cursor
-
-Open **Settings > MCP** and add the server URL, or add to `.cursor/mcp.json` in your project:
-
-```json
-{
-  "mcpServers": {
-    "bonnard": {
-      "url": "https://mcp.bonnard.dev/mcp"
-    }
-  }
-}
-```
-
-On first use, your browser will open to sign in and authorize the connection.
-
-### VS Code / GitHub Copilot
-
-Open the Command Palette and run **MCP: Add Server**, or add to `.vscode/mcp.json` in your project:
-
-```json
-{
-  "servers": {
-    "bonnard": {
-      "type": "http",
-      "url": "https://mcp.bonnard.dev/mcp"
-    }
-  }
-}
-```
-
-On first use, your browser will open to sign in and authorize the connection.
-
-### Claude Code
-
-Run in your terminal:
-
-```bash
-claude mcp add --transport http bonnard https://mcp.bonnard.dev/mcp
-```
-
-Or add to `.mcp.json` in your project:
-
-```json
-{
-  "mcpServers": {
-    "bonnard": {
-      "type": "http",
-      "url": "https://mcp.bonnard.dev/mcp"
-    }
-  }
-}
-```
-
-### Windsurf
-
-Open **Settings > Plugins > Manage plugins > View raw config**, or edit `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "bonnard": {
-      "serverUrl": "https://mcp.bonnard.dev/mcp"
-    }
-  }
-}
-```
-
-### Gemini CLI
-
-Add to `.gemini/settings.json` in your project or `~/.gemini/settings.json` globally:
-
-```json
-{
-  "mcpServers": {
-    "bonnard": {
-      "url": "https://mcp.bonnard.dev/mcp"
-    }
-  }
-}
-```
-
-## Authentication
-
-MCP uses OAuth 2.0 with PKCE. When an agent first connects:
-
-1. Agent discovers OAuth endpoints automatically
-2. You are redirected to Bonnard to sign in and authorize
-3. Agent receives an access token (valid for 30 days)
-
-No API keys or manual token management needed.
-
-## Available Tools
-
-Once connected, AI agents can use these MCP tools:
-
-| Tool | Description |
-|------|-------------|
-| `explore_schema` | Discover views and cubes, list their measures, dimensions, and segments. Supports browsing a specific source by name or searching across all fields by keyword. |
-| `query` | Query the semantic layer with measures, dimensions, time dimensions, filters, segments, and pagination. |
-| `sql_query` | Execute raw SQL against the semantic layer using Cube SQL syntax with `MEASURE()` for aggregations. Use for CTEs, UNIONs, and custom calculations. |
-| `describe_field` | Get detailed metadata for a field — SQL expression, type, format, origin cube, and referenced fields. |
-
-## Testing
-
-```bash
-# Verify the MCP server is reachable
-bon mcp test
-
-# View connection info
-bon mcp
-```
-
-## Managing Connections
-
-Active MCP connections can be viewed and revoked in the Bonnard dashboard under **MCP**.
-
-## See Also
-
-- workflow.deploy
-- workflow.query

package/dist/docs/topics/workflow.md

@@ -1,165 +0,0 @@
-# Workflow
-
-> The end-to-end workflow for building a semantic layer with Bonnard: validate your YAML definitions locally, deploy to the platform, and query your metrics via API or MCP.
-
-## Overview
-
-Building a semantic layer with Bonnard follows a development workflow: initialize a project, connect data sources, define cubes and views, validate, and deploy.
-
-## Quick Start
-
-```bash
-# 1. Initialize project
-bon init
-
-# 2. Add a data source
-bon datasource add
-
-# 3. Create cubes in bonnard/cubes/ and views in bonnard/views/
-
-# 4. Validate
-bon validate
-
-# 5. Deploy to Bonnard
-bon deploy -m "Initial semantic layer"
-```
-
-## Project Structure
-
-After `bon init`, your project has:
-
-```
-my-project/
-├── bon.yaml              # Project configuration
-├── bonnard/              # Semantic layer definitions
-│   ├── cubes/            # Cube definitions
-│   │   └── orders.yaml
-│   └── views/            # View definitions
-│       └── orders_overview.yaml
-└── .bon/                 # Local config (gitignored)
-    └── datasources.yaml  # Data source credentials
-```
-
-## Development Cycle
-
-### 1. Define Cubes
-
-Create cubes that map to your database tables:
-
-```yaml
-# bonnard/cubes/orders.yaml
-cubes:
-  - name: orders
-    sql_table: public.orders
-
-    measures:
-      - name: count
-        type: count
-
-    dimensions:
-      - name: status
-        type: string
-        sql: status
-```
-
-### 2. Define Views
-
-Create views that expose cubes to consumers:
-
-```yaml
-# bonnard/views/orders_overview.yaml
-views:
-  - name: orders_overview
-    cubes:
-      - join_path: orders
-        includes:
-          - count
-          - status
-```
-
-### 3. Validate
-
-Check for syntax errors and test connections:
-
-```bash
-bon validate
-```
-
-### 4. Deploy
-
-Push cubes and views to Bonnard:
-
-```bash
-bon deploy -m "Add orders cube and overview view"
-```
-
-### 5. Review
-
-Check what changed in your deployment:
-
-```bash
-bon deployments                       # List recent deployments
-bon diff <deployment-id>              # View all changes
-bon diff <deployment-id> --breaking   # Breaking changes only
-```
-
-## File Organization
-
-### One Cube Per File
-
-```
-bonnard/cubes/
-├── orders.yaml
-├── users.yaml
-├── products.yaml
-└── line_items.yaml
-```
-
-### Related Cubes Together
-
-```
-bonnard/cubes/
-├── sales/
-│   ├── orders.yaml
-│   └── line_items.yaml
-├── users/
-│   ├── users.yaml
-│   └── profiles.yaml
-└── products/
-    └── products.yaml
-```
-
-## Best Practices
-
-1. **Start from questions** — collect the most common questions your team asks, then build views that answer them. Don't just mirror your warehouse tables.
-2. **Add filtered measures** — if a dashboard card has a WHERE clause beyond a date range, that filter should be a filtered measure. This is the #1 way to match real dashboard numbers.
-3. **Write descriptions for agents** — descriptions are how AI agents choose which view and measure to use. Lead with scope, cross-reference related views, include dimension values.
-4. **Validate often** — run `bon validate` after each change
-5. **Test with real questions** — after deploying, ask an AI agent via MCP the same questions your team asks. Check it picks the right view and measure.
-6. **Iterate** — expect 2-4 rounds of deploying, testing with questions, and improving descriptions before agents reliably answer the top 10 questions.
-
-## Commands Reference
-
-| Command | Description |
-|---------|-------------|
-| `bon init` | Create project structure |
-| `bon datasource add` | Add a data source |
-| `bon datasource add --demo` | Add demo dataset (no warehouse needed) |
-| `bon datasource add --from-dbt` | Import from dbt profiles |
-| `bon datasource list` | List configured sources |
-| `bon validate` | Check cube and view syntax |
-| `bon deploy -m "message"` | Deploy to Bonnard (message required) |
-| `bon deploy --ci` | Non-interactive deploy |
-| `bon deployments` | List deployment history |
-| `bon diff <id>` | View changes in a deployment |
-| `bon annotate <id>` | Add context to deployment changes |
-| `bon query '{...}'` | Query the semantic layer |
-| `bon mcp` | MCP setup instructions for AI agents |
-| `bon docs` | Browse documentation |
-
-## See Also
-
-- workflow.validate
-- workflow.deploy
-- cubes
-- views