# TurboSteed CLI

Deploy and manage [TurboSteed](https://www.turbosteed.com) sites from your terminal or CI/CD pipeline.

## Features

- Deploy sites with a single command
- Manage assets (upload, list, delete)
- Retrieve contact form submissions
- Manage CMS schemas and entries
- Progress indicators and formatted output
- Works with GitHub Actions, GitLab CI, and Bitbucket Pipelines
- **MCP server** for Claude Code / Claude Desktop integration

## Requirements

- Node.js 18.0.0 or higher
- A TurboSteed account ([sign up](https://dashboard.turbosteed.com))

## Installation

### Global Installation (Recommended)

```bash
npm install -g @turbosteed/cli
```

Verify installation:

```bash
turbosteed --version
```

### Local Installation (Per Project)

```bash
npm install --save-dev @turbosteed/cli
```

Run via npx:

```bash
npx turbosteed deploy
```

Or add to `package.json` scripts:

```json
{
  "scripts": {
    "deploy": "turbosteed deploy --source ./dist"
  }
}
```

## Configuration

### Step 1: Get Your Credentials

1. Log in to the [TurboSteed Dashboard](https://dashboard.turbosteed.com)
2. Navigate to **Settings > API Keys**
3. Copy your **Account SID** and **API Key**
4. Navigate to your site and copy the **Site ID**

### Step 2: Set Environment Variables

```bash
export TURBOSTEED_ACCOUNT_SID="your-account-sid"
export TURBOSTEED_API_KEY="your-api-key"
export TURBOSTEED_SITE_ID="your-site-id"
```

For permanent setup, add these to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).

### Step 3 (Optional): Create a Config File

Create `turbosteed.json` in your project root:

```json
{
  "version": "1",
  "site": {
    "id": "your-site-id",
    "accountSid": "your-account-sid"
  },
  "deploy": {
    "source": "./dist",
    "exclude": ["**/*.map", ".DS_Store"]
  }
}
```

**Note:** Never put your API key in config files. Always use environment variables for secrets.

### Environment Variables Reference

| Variable | Required | Description |
|----------|----------|-------------|
| `TURBOSTEED_ACCOUNT_SID` | Yes | Your account identifier |
| `TURBOSTEED_API_KEY` | Yes | Your API key (keep secret) |
| `TURBOSTEED_SITE_ID` | Yes* | Site ID (*can be in config file) |
| `TURBOSTEED_API_BASE` | No | API base URL (defaults to production) |

## Usage

### Deploy a Site

```bash
# Deploy from ./dist (default)
turbosteed deploy

# Deploy from a specific directory
turbosteed deploy --source ./build

# Preview what would be deployed
turbosteed deploy --dry-run

# Output result as JSON
turbosteed deploy --json
```

**Requirements:**
- Source directory must contain an `index.html` file
- Maximum zip size: 25 MB

### Manage Assets

```bash
# Upload a file
turbosteed assets upload ./images/logo.png

# List first page of assets
turbosteed assets list

# List ALL assets (automatic pagination)
turbosteed assets list --all

# Manual pagination (next page)
turbosteed assets list --page <token>

# Delete an asset
turbosteed assets delete logo.png
```

### Contact Forms

```bash
# List first page of submissions
turbosteed forms list

# List ALL submissions (automatic pagination)
turbosteed forms list --all

# Manual pagination (next page)
turbosteed forms list --page <formId>

# Get a specific submission
turbosteed forms get <formId>
```

### CMS Content

```bash
# List first page of schemas
turbosteed cms schema list

# List ALL schemas (automatic pagination)
turbosteed cms schema list --all

# Create a schema from JSON file
turbosteed cms schema create ./blog-schema.json

# List first page of entries in a schema
turbosteed cms entry list <schemaId>

# List ALL entries (automatic pagination)
turbosteed cms entry list <schemaId> --all

# Create an entry
turbosteed cms entry create <schemaId> ./post.json

# Publish an entry
turbosteed cms entry publish <schemaId> <entryId>
```

**Example schema file (`blog-schema.json`):**

```json
{
  "display_name": "Blog Posts",
  "schema_mode": "custom",
  "fields": [
    { "name": "title", "type": "text", "required": true, "max_length": 200 },
    { "name": "slug", "type": "slug", "source_field": "title", "required": true },
    { "name": "body", "type": "richtext", "required": true },
    { "name": "published_date", "type": "date", "required": false }
  ]
}
```

**Example entry file (`post.json`):**

```json
{
  "title": "My First Post",
  "slug": "my-first-post",
  "body": "# Hello World\n\nThis is my first blog post.",
  "published_date": "2026-07-01"
}
```

## CI/CD Integration

### GitHub Actions

Create `.github/workflows/deploy.yml`:

```yaml
name: Deploy to TurboSteed

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install and Build
        run: npm ci && npm run build

      - name: Deploy to TurboSteed
        env:
          TURBOSTEED_ACCOUNT_SID: ${{ secrets.TURBOSTEED_ACCOUNT_SID }}
          TURBOSTEED_API_KEY: ${{ secrets.TURBOSTEED_API_KEY }}
          TURBOSTEED_SITE_ID: ${{ secrets.TURBOSTEED_SITE_ID }}
        run: npx @turbosteed/cli deploy --source ./dist
```

### GitLab CI

Create `.gitlab-ci.yml`:

```yaml
stages:
  - build
  - deploy

build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

deploy:
  stage: deploy
  image: node:20
  dependencies:
    - build
  script:
    - npx @turbosteed/cli deploy --source ./dist
  only:
    - main
```

### Bitbucket Pipelines

Create `bitbucket-pipelines.yml`:

```yaml
image: node:20

pipelines:
  branches:
    main:
      - step:
          name: Build
          caches:
            - node
          script:
            - npm ci
            - npm run build
          artifacts:
            - dist/**

      - step:
          name: Deploy to TurboSteed
          deployment: production
          script:
            - npx @turbosteed/cli deploy --source ./dist
```

## MCP Integration (Claude Code / Claude Desktop)

This CLI includes an MCP (Model Context Protocol) server that allows AI assistants like Claude to manage your TurboSteed site programmatically.

### Setup

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "turbosteed": {
      "command": "npx",
      "args": ["@turbosteed/cli", "--mcp"],
      "env": {
        "TURBOSTEED_ACCOUNT_SID": "your-account-sid",
        "TURBOSTEED_API_KEY": "your-api-key",
        "TURBOSTEED_SITE_ID": "your-site-id",
        "TURBOSTEED_API_BASE": "https://api-us.turbosteed.com"
      }
    }
  }
}
```

For Claude Code, add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "turbosteed": {
      "command": "npx",
      "args": ["@turbosteed/cli", "--mcp"],
      "env": {
        "TURBOSTEED_ACCOUNT_SID": "your-account-sid",
        "TURBOSTEED_API_KEY": "your-api-key",
        "TURBOSTEED_SITE_ID": "your-site-id",
        "TURBOSTEED_API_BASE": "https://api-us.turbosteed.com"
      }
    }
  }
}
```

### Starting the MCP Server Directly

You can also start the MCP server directly from the command line:

```bash
turbosteed --mcp
```

Or via npx:

```bash
npx @turbosteed/cli --mcp
```

### MCP Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TURBOSTEED_ACCOUNT_SID` | Yes | Account identifier (e.g., `AC...`) |
| `TURBOSTEED_API_KEY` | Yes | API key (e.g., `sk_...`) |
| `TURBOSTEED_SITE_ID` | Yes | Site identifier (e.g., `site_...`) |
| `TURBOSTEED_API_BASE` | No | API base URL (`https://api-us.turbosteed.com`) |

### How It Works

The CLI runs a local stdio MCP server that proxies all requests to the TurboSteed backend MCP HTTP endpoint at `${TURBOSTEED_API_BASE}/users/${accountSid}/sites/${siteId}/mcp`. It receives MCP protocol messages over stdio from Claude, forwards them via HTTP to the backend, and returns responses back through stdio.

### Available Tools

Once configured, Claude can use these tools:

| Tool | Description |
|------|-------------|
| `site.get` | Get site configuration |
| `site.update` | Update site settings |
| `cms.schema.list` | List CMS schemas |
| `cms.schema.get` | Get a schema definition |
| `cms.schema.create` | Create a new schema |
| `cms.entry.list` | List entries in a schema |
| `cms.entry.get` | Get a specific entry |
| `cms.entry.create` | Create a new entry |
| `cms.entry.update` | Update an entry |
| `cms.entry.publish` | Publish an entry |
| `webhooks.list` | List webhooks |
| `webhooks.create` | Create a webhook |
| `contacts.list` | List contact form submissions |
| `contacts.get` | Get a specific submission |
| `assets.list` | List all assets |
| `assets.delete` | Delete an asset |
| `deploy.getUploadUrl` | Get a pre-signed upload URL |
| `deploy.trigger` | Trigger deployment |
| `apikeys.getSiteCredentials` | Get public site credentials for RAG/widget |

### Example Usage

Ask Claude:
- "List all my CMS schemas"
- "Create a new blog post entry with title 'Hello World'"
- "Show me my site configuration"
- "What contact form submissions do I have?"

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Authentication failure |
| 3 | Resource not found |
| 4 | Upload/network failure |
| 5 | Invalid input |
| 6 | Configuration error |

## Alternative: Shell Scripts (No Node.js)

For environments without Node.js, use shell scripts:

```bash
curl -sSL https://raw.githubusercontent.com/turbosteed/shell-tools/main/scripts/deploy.sh | bash -s ./dist
```

See [github.com/turbosteed/shell-tools](https://github.com/turbosteed/shell-tools)

## Support

- [Documentation](https://docs.turbosteed.com)
- [Dashboard](https://dashboard.turbosteed.com)
- Email: support@turbosteed.com

## License

This software is licensed for use with TurboSteed accounts only. See [LICENSE](LICENSE) for full terms.