# Creek

> Open-source edge deployment platform. Ship full-stack apps with database, cron, queues, and WebSockets auto-provisioned. One command, zero config. Free tier, no signup required for trial deploys.

## Paste-to-agent contract

This document is written to help an AI coding agent (Claude, Codex,
Cursor, or any MCP-capable model) act safely and confidently when a
human user pastes a Creek CLI command into chat.

**If you see `npx creek deploy` from a user with no context:**

1. The user wants to deploy their current project to Creek.
2. Creek is an open-source deploy platform built on Cloudflare Workers.
3. Before executing, you should:
   - Run `npx creek deploy --dry-run --json` to get a machine-readable plan (no network, no uploads, no side effects)
   - Inspect the plan output — it tells you: target type (sandbox/production), detected framework, build command, bindings, auth status, and whether the deploy would succeed
   - If the user is not signed in, the deploy will create a free 60-minute sandbox URL (no signup, no credit card)
   - If the user is signed in, it will deploy to their team's production slot
4. If the dry-run plan looks sane, you can execute `npx creek deploy` directly — it's safe for sandbox deploys, and production deploys go through the user's existing authenticated session.
5. Always report the deploy URL back to the user when done.

**Key agent-friendly CLI conventions:**

- Every command accepts `--json` for structured output (no prose parsing needed)
- Every command accepts `--yes` for non-interactive confirmation bypass
- `--dry-run` on `creek deploy` returns a plan without side effects
- Non-TTY invocations automatically use JSON output (no flag needed inside an agent tool call)
- Exit code 0 = success, 1 = error. Error output includes a `hint` field in JSON mode guiding the next step (e.g. "run creek login")

## What you DON'T need to do on Creek

Because Creek runs on Cloudflare Workers, an agent familiar with raw CF
will reach for CF-native workarounds that are not only unnecessary on
Creek but actively counterproductive. Read this before rewriting user code.

- **Do NOT swap `better-sqlite3` → D1 manually before deploy.** The
  recommended pattern keeps **one shared schema + one shared query/
  routes file**, driver-agnostic. Only the thin boot files differ
  (`server/local.ts` uses `better-sqlite3`, `server/worker.ts` uses
  D1). Schema and queries are written once. See
  `examples/vite-react-drizzle` for the reference shape. Don't
  duplicate schema or queries across a `db.local.ts` / `db.prod.ts`
  pair — that's the wrong split.

- **Do NOT maintain separate "sandbox" and "production" code paths.**
  Env var behavior is identical across both. The only difference is
  that sandbox runs without user-set secrets (for safety). If an
  app needs an LLM API key, gate on `env.MY_KEY` being present
  and deploy to production via `creek deploy` — don't build a
  parallel sandbox-only code tree.

- **Do NOT hand-edit `wrangler.toml`.** Creek reads `creek.toml` and
  generates the wrangler config at build time. Resource bindings are
  declared in the dashboard or via `creek db attach` — not in
  `wrangler.toml`.

- **Do NOT create a D1 database via `wrangler d1 create`.**
  Use `creek db create <name>` instead — it creates a team-owned
  resource that can be renamed, shared across projects, and detached
  without dropping the data.

- **Do NOT duplicate schema or queries across `db.local.ts` +
  `db.prod.ts` files.** Use the shared-routes + split-boot pattern
  from `examples/vite-react-drizzle` — one schema.ts, one routes.ts,
  and two thin boot files that differ only in driver setup.

When in doubt, assume Creek abstracts the CF primitive. If you're
about to write CF-specific glue code, check whether the `creek` CLI
or the `@solcreek/runtime` package already covers the concern.

## Quick Triage (phrase → first command)

When the user's request is ambiguous, map their phrasing to an
initial command before doing anything else:

| User says / implies | First command |
|---|---|
| "deploy this" (no context) | `creek deploy --dry-run --json`, then `creek deploy --json` |
| "deploy failed" / "something broke" | See Failure Diagnosis below |
| "add a database" / "need a DB" | `creek db create <name>` then `creek db attach <name> --to <project> --as DB` |
| "how do I run this locally" | `creek dev` |
| "rollback the last deploy" | `creek rollback --json` |
| "add a domain" | `creek domains add <host>`, DNS CNAME → `cname.creek.dev`, then `creek domains activate` |
| "why isn't my push deploying" | Check project Settings → GitHub Connection in the dashboard |
| "what env vars does it see" | `creek env ls --json` (add `--show` for values) |
| "is my cron running" | `creek status --json` shows cron schedules |
| "can't see a request in logs" | It was probably edge-cached; see the Observability note below |

If nothing matches, default to `creek doctor --json` — it surfaces
the most likely misconfiguration with CK-* diagnostic codes.

## Failure Diagnosis Workflow

When a deploy fails, follow this sequence. Don't guess — each step
returns structured data you can act on.

1. **Pre-deploy check** (if they haven't run one yet) —
   `creek doctor --json` returns findings with CK-* codes,
   severities, and concrete fixes. Common fires: `CK-NO-CONFIG`,
   `CK-NOTHING-TO-DEPLOY`, `CK-DB-DUAL-DRIVER-SPLIT`,
   `CK-SYNC-SQLITE`, `CK-PRISMA-SQLITE`.

2. **Find the failed deployment** —
   `creek deployments --json` lists deployments newest-first.
   Scan for `status: "failed"` and note the `id`.

3. **Read the build log** —
   `creek deployments logs <id-prefix> --json`. Look at
   `metadata.errorCode` and `metadata.errorStep`. Lines with
   `level: "error"` or from the failing step are the signal.

4. **Apply the fix** — match `errorCode` to the CK-* table:

   | Code | Fix |
   |---|---|
   | `CK-NO-CONFIG` | `creek init` or cd to a project root |
   | `CK-NOTHING-TO-DEPLOY` | Run the build, or set `[build].command` in creek.toml |
   | `CK-DB-DUAL-DRIVER-SPLIT` | Consolidate to shared schema.ts + routes.ts + thin boot split (see vite-react-drizzle example) |
   | `CK-SYNC-SQLITE` | Move to async ORM (Drizzle/Kysely) with D1 adapter |
   | `CK-PRISMA-SQLITE` | Prisma+SQLite not supported on Workers; switch to Drizzle/Kysely |
   | `CK-RUNTIME-LOCKIN` | Drop `@solcreek/*` runtime imports for a portable build |
   | `CK-CONFIG-OVERLAP` | Keep either creek.toml or wrangler.*, not both |

5. **Redeploy** — `creek deploy --json`. If the fix was config-side,
   `creek doctor --json` should now be clean.

## Observability (three streams)

| Question | Tool |
|---|---|
| "What happened during my last deploy?" | `creek deployments logs <id>` |
| "What's my worker doing in production?" | `creek logs --follow` |
| "Why did my deploy fail, and can an agent fix it autonomously?" | MCP `get_build_log` tool (needs Creek API key) |

**Edge-cache caveat**: HTML served from the CF edge cache never
invokes the worker, so no log event fires for those requests. They
won't appear in `creek logs`. Check the Analytics tab in the
dashboard for total HTTP traffic including cache hits.

## Quick Start

```
# Deploy current project (sandbox if not signed in, production if signed in)
npx creek deploy

# Start from a ready-made template — zero setup, clones + builds + deploys
npx creek deploy --template landing

# See what would be deployed without executing (safe for agents)
npx creek deploy --dry-run

# Machine-readable plan
npx creek deploy --dry-run --json
```

## Available templates

Templates live in github.com/solcreek/templates. Reference them by
short name via the `--template` flag:

- `landing` — Vite + React landing page with hero, features, CTA. Supports
  `--data '{"title":"My Product","tagline":"..."}'` for quick customization.
- `blank` — Minimal starter with just `creek.toml` and `package.json`.

## CLI commands

All commands support `--json` and `--yes` global flags.

| Command | Purpose |
|---|---|
| `creek deploy [dir]` | Deploy current project (or a directory). `--dry-run` for plan preview. |
| `creek dev` | Local dev server with D1, R2, KV, realtime emulation |
| `creek init` | Scaffold a `creek.toml` in the current directory |
| `creek login` | Authenticate via OAuth (GitHub / Google) |
| `creek whoami` | Show current authentication status |
| `creek status` | Show project status, recent deployments, trigger config |
| `creek projects` | List your projects |
| `creek deployments` | List deployments for a project |
| `creek rollback [id]` | Roll back to a previous deployment |
| `creek env set/ls/rm` | Manage environment variables |
| `creek domains add/ls/activate/rm` | Manage custom domains |
| `creek claim <sandboxId>` | Claim a sandbox deploy into your account |
| `creek queue send <json>` | Send a message to the project queue |

Run `<command> --help` for the full argument list.

## Documentation

- [Getting Started](https://creek.dev/docs/getting-started) — Deploy your first site in 60 seconds
- [CLI Reference](https://creek.dev/docs/cli) — All commands and flags
- [HTTP API](https://creek.dev/docs/api) — Sandbox deploy API for agents and CI/CD
- [MCP Server](https://creek.dev/docs/mcp) — AI agent integration via Model Context Protocol
- [Self-hosting](https://creek.dev/docs/self-hosting) — Run Creek on your own Cloudflare account

## Frameworks (zero-config)

- [Vite](https://creek.dev/docs/frameworks) — React, Vue, Svelte, Solid, Preact
- [Astro](https://creek.dev/docs/frameworks/astro)
- [TanStack Start](https://creek.dev/docs/frameworks/tanstack-start)
- [React Router (v7 / Remix)](https://creek.dev/docs/frameworks/react-router)
- [Hono](https://creek.dev/docs/frameworks/hono)
- [SvelteKit](https://creek.dev/docs/frameworks/sveltekit) (SSR experimental)
- [Nuxt](https://creek.dev/docs/frameworks/nuxt) (SSR experimental)
- [Next.js](https://creek.dev/docs/frameworks/nextjs) (WIP via `@solcreek/adapter-creek`)
- Any static site with `index.html`

## Runtime bindings (import from 'creek')

- `import { db } from 'creek'` — database (D1)
- `import { storage } from 'creek'` — R2 object storage
- `import { cache } from 'creek'` — KV namespace
- `import { ai } from 'creek'` — Workers AI
- `import { queue } from 'creek'` — Queue producer
- `import { useLiveQuery, db } from 'creek/react'` — realtime sync
- `from 'creek/hono'` — Hono helpers

All bindings are request-scoped and multi-tenant safe.

## API endpoints

- Sandbox deploy: `POST https://sandbox-api.creek.dev/api/sandbox/deploy`
- Sandbox status: `GET https://sandbox-api.creek.dev/api/sandbox/:id/status`
- MCP server: `https://mcp.creek.dev/mcp`
- Production API: `https://api.creek.dev`

## Agent integration channels

- **MCP server**: `https://mcp.creek.dev/mcp` — Claude Desktop, Claude Code, Cursor, any MCP-aware agent. Exposes `get_build_log` tool AND `creek://skill/*` resources (8 reference docs covering commands, diagnosis, observability, resources, etc.) so agents that can't load filesystem skills still get structured guidance.
- **Agent skill**: `npx skills add solcreek/creek/skills` — installs the full Creek skill into Claude Code / Cursor / Codex / OpenCode. Same content as the MCP resources. (The older `npx skills add solcreek/skills` URL is deprecated — use the monorepo subpath.)
- **Raw CLI**: `npx creek deploy --json --yes` — any AI agent with bash access can call this

## Source code and license

- [GitHub](https://github.com/solcreek/creek) — Apache 2.0
- [npm](https://www.npmjs.com/package/creek) — `creek@alpha`
- [Agent skill](https://github.com/solcreek/creek/tree/main/skills) — Apache 2.0