# Push Command

The `push` command builds Supabase migrations from growth loop telemetry definitions and optionally pushes the artifacts to Skene Cloud upstream.

## Prerequisites

Before running `push`, you need:

- Growth loop definitions with Supabase telemetry in `skene-context/growth-loops/`. These are generated by the `build` command. See [Build](build.md) for details.
- For upstream push: authentication via `skene login`. See [Login](login.md).

## Basic usage

Generate a Supabase migration from all growth loops with telemetry:

```bash
uvx skene push
```

Push a specific loop by ID:

```bash
uvx skene push --loop my_activation_loop
```

Push to upstream (Skene Cloud):

```bash
uvx skene push --upstream https://skene.ai/workspace/my-app
```

## Flag reference

| Flag | Short | Description |
|------|-------|-------------|
| `PATH` | | Project root directory (default: `.`) |
| `--context PATH` | `-c` | Path to `skene-context` directory (auto-detected if omitted) |
| `--loop TEXT` | `-l` | Push only this loop by `loop_id`. If omitted, pushes all loops with Supabase telemetry. |
| `--upstream TEXT` | `-u` | Upstream workspace URL (e.g. `https://skene.ai/workspace/my-app`). Resolved from `.skene.config` or this flag. |
| `--push-only` | | Re-push current output without regenerating migrations |

## How it works

### Step 1: Load growth loops

The command loads all growth loop JSON files from `skene-context/growth-loops/` and filters for loops that have Supabase telemetry (telemetry items with `type: "supabase"`).

### Step 2: Generate Supabase migration

For each loop with Supabase telemetry, the command generates SQL trigger functions that:

- Create a trigger on the specified table for the specified operation (INSERT, UPDATE, or DELETE)
- INSERT a row into `skene.event_log` with the captured properties
- Use idempotent DDL (DROP TRIGGER IF EXISTS before CREATE)

The migration is written to `supabase/migrations/<timestamp>_skene_telemetry.sql`.

### Step 3: Push to upstream (optional)

When an upstream URL is configured (via `--upstream` or `.skene.config`), the command packages the growth loops and telemetry SQL and sends them to the upstream API at `POST https://www.skene.ai/api/v1/deploys`.

## Base schema

Right now init create the sql files required for deploying skene schema to supabase without connecting Skene Cloud at all. The goal is to increase security.

Before pushing telemetry migrations, you need the base schema. Run `skene init` to create it:

```bash
uvx skene init
```

This creates `supabase/migrations/20260201000000_skene_schema.sql` with:

- `skene.event_log` — universal sink for allowlisted triggers
- `skene.failed_events` — dead-letter queue for events exceeding retry limits
- `skene.enrichment_map` — rules table for metadata enrichment

## Telemetry format

Growth loops include telemetry definitions that describe what events to capture. The Supabase telemetry type looks like:

```json
{
  "type": "supabase",
  "table": "documents",
  "operation": "INSERT",
  "properties": ["id", "name", "created_at"],
  "action_name": "document_insert"
}
```

The `push` command converts these into SQL trigger functions automatically.

## Upstream authentication

To push to upstream, authenticate first:

```bash
uvx skene login --upstream https://skene.ai/workspace/my-app
```

The upstream URL can also be resolved from:

1. `upstream` field in `.skene.config` (saved by `skene login`)
2. `--upstream` CLI flag (highest priority)

## Next steps

- [Login](login.md) -- Authenticate with Skene Cloud upstream
- [Build](build.md) -- Generate growth loop definitions with telemetry
- [Status](status.md) -- Verify growth loop implementation
- [CLI Reference](../reference/cli.md) -- Full reference for all commands and flags
