Quickstart

This walkthrough takes you from an empty account to a running app — with its own database and, optionally, a custom domain. Comwit Cloud groups your resources under a project: databases, runtime apps, and domains all live inside one.

Everything here uses the comwit command-line tool (CLI), and every step maps to a public API call you could script instead. The CLI talks to the API host at https://api.cloud.comwit.io; the console is at https://cloud.comwit.io.

Before you start

You’ll need the CLI installed and a project to work in. The Install the CLI guide covers setup; this page assumes you’ve finished it.

1. Install and log in

   Install the CLI, confirm it runs, then sign in. comwit login uses a device flow: it opens your browser and asks you to enter a short code.

   Install and authenticate

   scripts/install-comwit.sh          # builds/installs comwit to ~/.local/bin
   comwit version
   comwit login                       # device flow: opens browser, enter the code

   After login, your token is stored at ~/.config/comwit/config.json. Pin a default project so you can leave off --project in 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 list

   See Authentication for scopes and token details.

2. 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-db

   The output includes a DATABASE_ID, a DATABASE_URL, and — when one is issued — a one-time token.

   Copy the token now

   The database token is shown once and is never stored by Comwit. Copy it immediately; if you lose it you’ll have to rotate the credential. Your app connects using the URL plus this token.

   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.

3. 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 web

   The 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 setting DATABASE_URL. Environment is set through the API or the console:

   Set an environment variable (API)

   PUT /v1/projects/{projectId}/apps/{appId}/environment/DATABASE_URL

   See Configure environment & secrets for the full flow.

4. Deploy a build

   Now ship your built code. --package accepts a built directory (which the CLI auto-packs to .tar.zst) or a prebuilt .tar.zst archive.

   Deploy

   comwit deploy --project <projectId> --app <appId> --package ./dist

   The 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.

5. (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.com

   This 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.com

   Once the check reports matched: true, the domain is managed. You can then attach a hostname to your app. Under a managed project domain you can use Automatic DNS (the API sets dns_mode: "managed_project_domain") so Comwit writes the records for you; otherwise you get Manual DNS records to publish yourself.

   See Bring your own domain and Connect a domain to an app.

What you just used

Every CLI command above maps to a public API route, so you can automate the same flow from a script or your CI:

Step	CLI	API route
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 app	comwit apps create	POST /v1/projects/{projectId}/apps
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

Next steps

Ready to go deeper? Explore Databases, Apps, and Domains, or learn to drive everything from the API.