CLI reference

The comwit CLI is the command-line tool for Comwit Cloud. You use it from your terminal to log in, deploy runtime apps, create databases, and manage project domains and DNS records.

Under the hood every command talks to the public platform API at https://api.cloud.comwit.io. The CLI never calls cloud infrastructure directly, so anything you can do here you could also do with a plain HTTP request — each section below shows the matching API route.

Note

This page is the exhaustive command reference. If you are new, start with Install the CLI and the Quickstart, then come back here.

Install

The fastest way to get the CLI is the install script:

Install comwit

scripts/install-comwit.sh

The installer first tries to download a GitHub release asset named like comwit_<os>_<arch>.tar.gz. Until releases exist, it falls back to building the CLI from the current checkout and installs the binary to ~/.local/bin/comwit.

You can influence the installer with environment variables:

Installer environment variables

COMWIT_VERSION=v0.1.0 scripts/install-comwit.sh
COMWIT_INSTALL_DIR=/usr/local/bin scripts/install-comwit.sh
COMWIT_INSTALL_REPO=comwit/comwit-cloud scripts/install-comwit.sh

Variable	What it does
COMWIT_VERSION	Pin the release tag to download instead of the latest.
COMWIT_INSTALL_DIR	Install the binary somewhere other than ~/.local/bin.
COMWIT_INSTALL_REPO	Point the installer at a different GitHub repository.

Build from source

If you are working from a checkout of the repository, you can build the CLI directly. The source lives in tools/comwit.

Build the CLI

just cli-test
just cli-build
./dist/comwit version

Authentication

Before any project command works you need to log in. The CLI stores a personal access token (a cwt_ token) and uses it on every request.

Log in

comwit login                                  # device flow (recommended)
comwit login --project <project-id>
comwit login --token <token>                  # paste an existing PAT
comwit login --token <token> --project <project-id>

comwit login with no token runs the device authorization flow: it opens your browser so you can approve a short code, then stores the issued cwt_ token for you.

You can also paste a cwt_ personal access token that you created from the dashboard at cloud.comwit.io/tokens (“API tokens”). The plaintext token is shown only once at creation, so copy it then. Revoke a token from the same dashboard page.

Your token is scoped to the projects you can access, so apps, deploy, and databases only act on those projects — anything else returns HTTP 403.

Caution

Never use PLATFORM_API_SERVER_TOKEN as your CLI token. That is a server-side operator guard, not a user credential. User tokens always start with cwt_. Do not publish a server token in CLI examples, issue reports, or any browser-visible configuration.

Configuration and environment

Setting	Default / variable	Purpose
Token config file	~/.config/comwit/config.json	Where the issued cwt_ token is stored.
COMWIT_CONFIG	(overrides the path above)	Use a different config file location.
COMWIT_PROJECT	(overrides the default)	Default project for commands that accept --project.

The CLI always targets https://api.cloud.comwit.io. Local AWS, Louhi management, brrrd-control, and registry calls are outside the CLI contract.

See Authentication for token scopes and details.

Projects

List projects

comwit projects list

Scaffolded

Project listing is scaffolded for the CLI, but full user-scoped project listing depends on a future authz/project API pass. Today the command calls the platform API first and falls back to your configured default project when the API does not yet expose user project listing.

Most other commands take a --project <project-id> flag (or read COMWIT_PROJECT) to choose which project to act on.

Runtime apps

Runtime apps are the deployable services in a project. You list them, create them, push a deployment, and inspect builds.

App commands

comwit apps list --project <project-id>
comwit apps create --project <project-id> --name web
comwit deploy --project <project-id> --app <app-id> --package ./apps/web/dist/brrrd
comwit apps builds --project <project-id> --app <app-id>

Deploy

The deploy command accepts either a prebuilt package file or a brrrd output directory. When you point --package at a directory, the CLI uses local tar --zstd to create a temporary .tar.zst archive for upload.

Note

If your local tar does not support zstd, pass a prebuilt package file instead of a directory.

Deploy also accepts several optional flags:

Deploy with optional flags

comwit deploy \
  --project <project-id> \
  --app <app-id> \
  --package ./dist/brrrd \
  --host app.example.com \
  --env-ref brrrd/env/app \
  --max-concurrent-requests 100

Flag	Required	Purpose
--project	yes	Project that owns the app.
--app	yes	App to deploy to.
--package	yes	Prebuilt package file, or a brrrd output directory to archive and upload.
--host	no	Hostname to serve this deployment on.
--env-ref	no	Reference to the environment configuration to apply.
--max-concurrent-requests	no	Cap on concurrent requests for the deployment.

Domains

Project-domain commands manage delegated DNS through the platform API using your cwt_ token. The CLI never calls AWS directly.

Domain commands

comwit domains list --project <project-id>
comwit domains add --project <project-id> --domain example.com
comwit domains check --project <project-id> --domain example.com
comwit domains delete --project <project-id> --domain example.com

Command	What it does
domains add	Creates a Route 53 public hosted zone through platform-api and prints the nameservers you must set at your current registrar.
domains check	Asks platform-api to resolve authoritative NS records and report whether the domain is managed.
domains delete	Removes a domain from Comwit management. Platform-api deletes active Route 53 records (including platform-owned app records), then deletes the hosted zone and soft-deletes product state.

See Bring your own domain for the end-to-end setup flow.

DNS records

DNS record management uses nested commands under domains records.

List records

comwit domains records list --project <project-id> --domain example.com

Create a record

comwit domains records create \
  --project <project-id> \
  --domain example.com \
  --name www \
  --type CNAME \
  --value target.example.net \
  --ttl 300

Update a record (partial)

comwit domains records update \
  --project <project-id> \
  --domain example.com \
  --record <record-id> \
  --value target2.example.net \
  --ttl 300

Delete a record

comwit domains records delete \
  --project <project-id> \
  --domain example.com \
  --record <record-id>

Partial updates

domains records update is partial: omitted --name, --type, and --ttl values are loaded from the existing record. Supplying one or more --value flags replaces the record values.

Record flags

Flag	Used by	Purpose
--name	create, update	Record name (e.g. www). Loaded from the existing record on update if omitted.
--type	create, update	Record type (e.g. CNAME). Loaded from the existing record on update if omitted.
--value	create, update	Record value(s). Supplying one or more replaces the record values.
--ttl	create, update	Time-to-live in seconds. Loaded from the existing record on update if omitted.
--record	update, delete	Record id to target.

Scopes and locking

Required scopes are domain:read for list and read operations, and domain:write for add, check, create, update, and delete.

Delegation locking

If a delegation check downgrades a project domain to pending_delegation, you can still delete existing DNS records, but create and update remain locked until your nameservers match again.

Domain purchase is not in the CLI

Domain purchase commands are intentionally not part of the CLI until Route 53 Domains billing, contact, auto-renew, and transfer-out policy is implemented.

Caution

Even though AWS offers Route 53 Domains CLI commands, the comwit CLI must never ask you to run the AWS CLI against the Comwit AWS account. Future purchase commands will call platform-api instead. See Remove and purchase domains.

Databases

Database commands

comwit databases create --project <project-id> --name production
comwit databases list --project <project-id>

These commands call the project-scoped database routes through platform-api and print the database id, status, and URL. Databases created from the CLI also appear in the dashboard.

See Create and connect a database for how to get a connection string and start running SQL.

API routes used by the CLI

Every command above maps to a route on the public, project-shaped platform API. If you prefer to call the API directly, these are the routes the CLI uses:

Public API contract

GET    /v1/projects/{projectId}/apps
POST   /v1/projects/{projectId}/apps
POST   /v1/projects/{projectId}/apps/{appId}/deployments
GET    /v1/projects/{projectId}/apps/{appId}/builds
GET    /v1/projects/{projectId}/domains
POST   /v1/projects/{projectId}/domains
GET    /v1/projects/{projectId}/domains/{domain}
DELETE /v1/projects/{projectId}/domains/{domain}
POST   /v1/projects/{projectId}/domains/{domain}/delegation-check
GET    /v1/projects/{projectId}/domains/{domain}/records
POST   /v1/projects/{projectId}/domains/{domain}/records
PUT    /v1/projects/{projectId}/domains/{domain}/records/{recordId}
DELETE /v1/projects/{projectId}/domains/{domain}/records/{recordId}

CLI command	Route
apps list	GET /v1/projects/{projectId}/apps
apps create	POST /v1/projects/{projectId}/apps
deploy	POST /v1/projects/{projectId}/apps/{appId}/deployments
apps builds	GET /v1/projects/{projectId}/apps/{appId}/builds
domains list	GET /v1/projects/{projectId}/domains
domains add	POST /v1/projects/{projectId}/domains
domains check	POST /v1/projects/{projectId}/domains/{domain}/delegation-check
domains delete	DELETE /v1/projects/{projectId}/domains/{domain}
domains records list	GET /v1/projects/{projectId}/domains/{domain}/records
domains records create	POST /v1/projects/{projectId}/domains/{domain}/records
domains records update	PUT /v1/projects/{projectId}/domains/{domain}/records/{recordId}
domains records delete	DELETE /v1/projects/{projectId}/domains/{domain}/records/{recordId}

Note

GET /v1/projects/{projectId}/domains/{domain} returns a single domain’s details. Hidden compatibility routes such as /v1/runtime/tenants/... are not CLI contracts and should not be relied on.

For more on the API itself, see the API overview and Authentication.