Quickstart
This walkthrough takes you from an empty account to a running app — with its own database and, optionally, a repository, Storage, and a custom domain. Comwit Cloud groups your databases, repositories, Storage resources, runtime apps, and domains under one project.
The CLI manages databases and apps, the console creates repositories, and Git
clones and pushes code. Cloud resource actions also have public API routes you
can script. The API host is https://api.cloud.comwit.io; the console is at
https://cloud.comwit.io.
-
Install and log in
Section titled “Install and log in”Install the CLI, confirm it runs, then sign in.
comwit loginuses a device flow: it opens your browser and asks you to enter a short code.Install and authenticate curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | shcomwit versioncomwit login # device flow: opens browser, enter the codeAfter login, your token is stored at
~/.config/comwit/config.json. Pin a default project so you can leave off--projectin later commands:Pin a default project comwit login --project <projectId># or, with an existing token:comwit login --token cwt_xxx --project <projectId>User tokens always start with
cwt_. Don’t have your project id handy? List your projects:Find your project id comwit projects listSee Authentication for scopes and token details.
-
Create a database
Section titled “Create a database”Each app usually needs somewhere to store data. Create a database in your project:
Create a database comwit databases create --project <projectId> --name app-dbThe output includes a
DATABASE_ID, aDATABASE_URL, and — when one is issued — a one-timetoken.The connection URL points at the database data endpoint:
DATABASE_URL DATABASE_URL = https://db.cloud.comwit.io/v1/<tenant_id>/See Create & connect a database for connecting, and Run SQL for querying.
-
(Optional) Create Storage
Section titled “(Optional) Create Storage”Create an S3-compatible object bucket when the app stores uploads or assets:
Create Storage comwit storage create \--project <projectId> \--name <globally-unique-bucket> \--publicSave the returned
storage_id, bucket, endpoint, and public base URL. A deployed app should use a projectcwp_token with the minimum Storage scopes. See Create and connect Storage. -
Create a runtime app
Section titled “Create a runtime app”A runtime app is the deploy target that serves your code. Create one:
Create an app comwit apps create --project <projectId> --name webThe output includes an
APP_ID. Set any environment variables your app needs (plain string values only) — for example, point your app at the database by settingDATABASE_URLandDATABASE_AUTH_TOKEN:Set app environment comwit apps env set --project <projectId> --app <appId> DATABASE_URL https://db.cloud.comwit.io/v1/<tenant_id>/comwit apps env set --project <projectId> --app <appId> DATABASE_AUTH_TOKEN <database_token>App environment values are plain text today. See Environment variables for the full flow and caveats.
-
(Optional) Push code to a repository
Section titled “(Optional) Push code to a repository”comwit loginin step 1 also configures Git access. In the console, open Project → Repositories → Create repository and enter a name. When it is ready, copy its clone URL, then clone, commit, and push:Push code git clone https://git.cloud.comwit.io/<projectId>/<repositoryId>.gitcd <repositoryId>git add .git commit -m "Initial commit"git push -u origin HEADAdd your project files before
git add. Git uses the token fromcomwit login, so no password prompt is needed when its credential helper was configured. See Create and connect a repository. -
Deploy a build
Section titled “Deploy a build”Now ship your built code.
--packageaccepts a built directory (which the CLI auto-packs to.tar.zst) or a prebuilt.tar.zstarchive.Deploy comwit deploy --project <projectId> --app <appId> --package ./distThe deploy uploads the artifact and activates a new
build_id. Useful optional flags:--host a.example.com,b.example.com— attach hostnames during deploy--env-ref <ref>— pin a specific environment reference--max-concurrent-requests <n>— cap concurrency
Review history (and roll back if you need to) with:
List builds comwit apps builds --project <projectId> --app <appId>See Deploy an app for deploys, rollbacks, and build history.
-
(Optional) Bring a domain and attach a hostname
Section titled “(Optional) Bring a domain and attach a hostname”If you own a domain, you can onboard it for delegated DNS. Add it to your project:
Add a domain comwit domains add --project <projectId> --domain example.comThis returns a set of Route 53 nameservers. Update the nameservers at your registrar, then confirm the delegation took effect:
Check delegation comwit domains check --project <projectId> --domain example.comOnce the check reports
matched: true, the domain ismanaged. You can then attach a hostname to your app. Under a managed project domain you can use Automatic DNS (the API setsdns_mode: "managed_project_domain") so Comwit writes the records for you; otherwise you get Manual DNS records to publish yourself.
What you just used
Section titled “What you just used”Cloud resource actions map to public API routes. Git content uses the Git host:
| Step | Tool | Endpoint |
|---|---|---|
| Log in | comwit login | POST /v1/auth/device, .../device/token |
| List projects | comwit projects list | GET /v1/projects |
| Create DB | comwit databases create | POST /v1/projects/{projectId}/databases |
| Create Storage | comwit storage create | POST /v1/projects/{projectId}/storages |
| Create app | comwit apps create | POST /v1/projects/{projectId}/apps |
| Create repository | Console | POST /v1/projects/{projectId}/repositories |
| Clone and push | git clone, git push | https://git.cloud.comwit.io/<projectId>/<repositoryId>.git |
| Deploy | comwit deploy | POST /v1/projects/{projectId}/apps/{appId}/deployments |
| Add domain | comwit domains add | POST /v1/projects/{projectId}/domains |
| Check delegation | comwit domains check | POST .../domains/{domain}/delegation-check |