Skip to content

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.

  1. 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
    curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | sh
    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. 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.

    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 an S3-compatible object bucket when the app stores uploads or assets:

    Create Storage
    comwit storage create \
    --project <projectId> \
    --name <globally-unique-bucket> \
    --public

    Save the returned storage_id, bucket, endpoint, and public base URL. A deployed app should use a project cwp_ token with the minimum Storage scopes. See Create and connect Storage.

  4. 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 and DATABASE_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.

  5. comwit login in 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>.git
    cd <repositoryId>
    git add .
    git commit -m "Initial commit"
    git push -u origin HEAD

    Add your project files before git add. Git uses the token from comwit login, so no password prompt is needed when its credential helper was configured. See Create and connect a repository.

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

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

Cloud resource actions map to public API routes. Git content uses the Git host:

StepToolEndpoint
Log incomwit loginPOST /v1/auth/device, .../device/token
List projectscomwit projects listGET /v1/projects
Create DBcomwit databases createPOST /v1/projects/{projectId}/databases
Create Storagecomwit storage createPOST /v1/projects/{projectId}/storages
Create appcomwit apps createPOST /v1/projects/{projectId}/apps
Create repositoryConsolePOST /v1/projects/{projectId}/repositories
Clone and pushgit clone, git pushhttps://git.cloud.comwit.io/<projectId>/<repositoryId>.git
Deploycomwit deployPOST /v1/projects/{projectId}/apps/{appId}/deployments
Add domaincomwit domains addPOST /v1/projects/{projectId}/domains
Check delegationcomwit domains checkPOST .../domains/{domain}/delegation-check