# Clouzark

> Clouzark is a developer cloud with two services: web hosting for Next.js, React, Node, and static sites (Vercel-style: GitHub or upload deploys, preview and production environments, environment variables, custom domains) and managed Postgres databases (Supabase-style: SQL, migrations, generated TypeScript types, an auto-generated REST API, end-user auth, storage, and realtime). Everything here can be done with the `clouzark` CLI, its MCP server, or the Management API.

Full documentation: https://docs.clouzark.com (index for agents: https://docs.clouzark.com/llms.txt).

Key facts for agents:
- A team (organization) owns hosting projects and database projects. Access follows the user's team role: viewer (read), member (deploy, run SQL, apply migrations), owner (env vars, domains, deleting databases).
- A repo is linked to at most one hosting project and one database project, stored in `.clouzark/project.json` (git-ignored). Commands without a project argument use those links.
- Deployments build from GitHub (the latest pushed commit of a branch) unless uploaded with `--upload`. Pushes to the production branch deploy to production; other branches are previews.
- Database migrations live in `clouzark/migrations/<UTC timestamp>_<name>.sql`. Each runs in one transaction; never include BEGIN/COMMIT or CREATE INDEX CONCURRENTLY, and never edit an applied migration (add a new one).
- Environment variable changes only reach the app after a redeploy.

## MCP server (preferred for agents)

Run the CLI as an MCP server over stdio; it uses the CLI's login and the linked projects of its working directory.

```
npm i -g clouzark && clouzark login
claude mcp add clouzark -- clouzark mcp            # Claude Code
claude mcp add clouzark -- clouzark mcp --read-only
```

Other clients: command `clouzark`, args `["mcp"]` (add `"--read-only"` to expose only reading tools; SQL then runs in a read-only transaction). `--project <ref>` and `--db <ref>` set defaults.

Tools: whoami, list_projects, list_deployments, get_deployment (status plus build log tail; poll until `done`), list_env, list_domains, list_databases, get_api_keys (REST URL and anon key), execute_sql, list_migrations, generate_types, and outside read-only mode: create_project, deploy (git or `upload: true`), redeploy, promote_deployment, rollback, set_env, remove_env, add_domain, remove_domain, create_database, apply_migration (also writes the migration file).

## CLI

Install: `npm i -g clouzark` (or `npx clouzark <command>`). Node 20+.

Auth and setup:
- `clouzark login` — browser approval; `--token cz_pat_...` for CI (or set `CLOUZARK_TOKEN`). `--api-url` for self-hosted instances.
- `clouzark whoami`, `clouzark logout`
- `clouzark link [--project <ref>]` links the hosting project; `clouzark db link [--db <ref>]` links the database.
- `clouzark init` links projects and writes agent instructions (AGENTS.md).

Web hosting:
- `clouzark deploy [--prod] [--branch <b>] [--no-wait]` — build the latest pushed commit; streams the build log.
- `clouzark deploy --upload [--prod]` — build the working directory as-is (uncommitted changes included; .env files are never sent; 100 MB limit).
- `clouzark deployments ls`, `clouzark logs [deploymentId] [-f]`
- `clouzark promote <deploymentId>`, `clouzark rollback`, `clouzark redeploy [deploymentId]`, `clouzark cancel <deploymentId>`
- `clouzark env ls | add <KEY> [value] [-t all|production|preview] | rm <KEY> [-t ...] | pull [file] [-e production|preview]`
- `clouzark domains ls | add <hostname> | verify <hostname> | rm <hostname>`
- `clouzark projects ls`, `clouzark projects create [owner/repo] [--name <n>] [--root <dir>]` — import a GitHub repo as a project (links it and follows the first build)

Database:
- `clouzark db ls | create <name> | delete <ref> | link`
- `clouzark db query "<sql>"` (or `-f file.sql`, or stdin; `--json`)
- `clouzark db url` (postgres:// connection string), `clouzark db keys` (REST URL, anon key, service key), `clouzark db dump [-f file] [--data-only|--full]` (needs local pg_dump)
- `clouzark migration new <name>`, `clouzark migration ls`, `clouzark db push [--dry-run] [--yes]`
- `clouzark gen types typescript [-o src/database.types.ts]`

Common flags: `-p, --project <ref>` (hosting) and `--db <ref>` (database) override the links; list commands take `--json`. Environment: `CLOUZARK_TOKEN`, `CLOUZARK_API_URL`, `CLOUZARK_PROJECT`, `CLOUZARK_DB`.

## Management API

Base URL `https://api.clouzark.com/v1`. Send `Authorization: Bearer cz_pat_...` (a team-scoped token from Team Settings → Access Tokens, or `clouzark login`). JSON in and out; errors are `{ "error": "..." }`. 120 requests a minute per token. `:ref` is a slug or id.

Account:
- `GET /me` — user, team, role, token expiry
- `DELETE /tokens/current` — revoke the calling token

Hosting projects:
- `GET /projects`, `GET /projects/:ref`
- `POST /projects` `{ repo: "owner/name", name?, root_directory?, framework?, production_branch?, install_command?, build_command?, output_directory? }` — import a GitHub repo; returns `{ project, deployment_id }` for the first production build
- `GET /projects/:ref/deployments?limit=20`
- `POST /projects/:ref/deployments` `{ "branch"?: string }` — build the branch's latest pushed commit (production branch by default)
- `POST /projects/:ref/deployments/upload?environment=preview|production&branch=&git_sha=&message=` — body is a .tar.gz of the project (`Content-Type: application/gzip`); regular files and directories only
- `POST /projects/:ref/rollback`
- `GET /deployments/:id?log_offset=0` — deployment (`status`: queued, building, deploying, live, failed, canceled, stopped; `done`), `log` from `log_offset`, `log_length`
- `POST /deployments/:id/promote | /redeploy | /cancel`
- `GET /projects/:ref/env` (names and targets), `GET /projects/:ref/env/values?environment=preview|production` (resolved values), `POST /projects/:ref/env` `{ key, value, target }`, `DELETE /projects/:ref/env/:key?target=all`
- `GET /projects/:ref/domains`, `POST /projects/:ref/domains` `{ hostname }`, `POST /projects/:ref/domains/:hostname/verify`, `DELETE /projects/:ref/domains/:hostname` — domains include `dns.cname` / `dns.a` targets

Database projects:
- `GET /database-projects`, `GET /database-projects/:ref`, `POST /database-projects` `{ name }`, `DELETE /database-projects/:ref`
- `POST /database-projects/:ref/query` `{ sql, read_only?: boolean }` → `{ command, row_count, fields, rows, duration_ms }`
- `GET /database-projects/:ref/migrations`, `POST /database-projects/:ref/migrations` `{ version: "YYYYMMDDHHMMSS", name, sql }` (re-sending the same SQL is a no-op; different SQL for an applied version is a 409)
- `GET /database-projects/:ref/types/typescript` → `{ types }`
- `GET /database-projects/:ref/keys` → `{ rest_url, anon_key, service_key }`
- `GET /database-projects/:ref/credentials` → host, port, database, username, password, ssl, connection_string

## Database APIs (for apps)

Each database project has public APIs at `https://api.clouzark.com/<api>/<project ref>`, called with an `apikey` header:
- anon key: safe in browsers; row-level security policies apply.
- service key: server-side only; bypasses row-level security.
- `Authorization: Bearer <end-user token>` (from Auth below) acts as that user; `auth.uid()` returns their id in policies.

REST — `/rest/<ref>/<table>`:
- `GET /rest/<ref>/<table>?page=1` → `{ columns, rows, total, pageSize }` (50 per page)
- `GET /rest/<ref>/<table>/<id>`, `POST /rest/<ref>/<table>` (JSON row), `PATCH /rest/<ref>/<table>/<id>`, `DELETE /rest/<ref>/<table>/<id>` → `{ row }`

GraphQL — `POST /graphql/<ref>` with `{ query, variables }`.

Auth (end users of your app) — `/auth/<ref>`:
- `POST /signup`, `POST /login` `{ email, password }` → `{ user, token }`
- `GET /me`, `PUT /user`, `POST /logout`, `POST /magiclink`, `POST /recover`, MFA under `/factors`

Storage — `/storage/<ref>`:
- `POST|PUT /object/<bucket>/<path>` (raw body; `x-upsert: true` to overwrite with POST), `GET /object/<bucket>/<path>`, `DELETE /object/<bucket>/<path>`
- `GET /public/<bucket>/<path>` (public buckets), `GET /list/<bucket>?prefix=&limit=&offset=`, `POST /sign/<bucket>/<path>` `{ expiresIn }`

Realtime — `/realtime/<ref>/channels/<channel>`: `GET` subscribes (Server-Sent Events), `POST .../broadcast` publishes, `GET|POST .../presence` reads or sets presence. `private:` channels refuse the anon key.