Skip to content

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.

The canonical implementation, version, and release source is burrr-ai/comwit-cli.

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.

Recommended for macOS and Linux:

Install comwit
curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | sh
comwit version

The npm package is the cross-platform mirror for macOS, Linux, and Windows:

Install with npm
npm install -g comwit-cli
comwit version

Run the npm package without installing it:

Run with npx
npx comwit-cli version

The standalone installer downloads a GitHub release asset from burrr-ai/comwit-cli, named like comwit_<os>_<arch>.tar.gz, and installs the comwit binary.

You can influence the standalone installer with environment variables:

Installer environment variables
curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | COMWIT_VERSION=vX.Y.Z sh
VariableWhat it does
COMWIT_VERSIONPin the release tag to download instead of the latest.

If you want to build the CLI directly, use the public source repository:

Build the CLI
git clone https://github.com/burrr-ai/comwit-cli.git
cd comwit-cli
go test ./...
go build -trimpath -o ./dist/comwit ./cmd/comwit
./dist/comwit version

For npm installs, update through npm:

Update npm install
npm install -g comwit-cli@latest

For standalone installs, update the current binary in place from the latest GitHub release:

Update comwit
comwit update

Pin a release tag or repository when needed:

Update options
comwit update --version vX.Y.Z
comwit update --repo burrr-ai/comwit-cli

comwit update downloads the asset matching the current OS and architecture (comwit_darwin_arm64.tar.gz, comwit_linux_amd64.tar.gz, and so on), extracts the comwit executable, and atomically replaces the running binary. It supports macOS and Linux on amd64 and arm64.

Private release downloads use COMWIT_UPDATE_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN, or gh auth token. These are GitHub credentials only; they are unrelated to your cwt_ Comwit API token.

Use the setup action when a GitHub Actions workflow needs comwit available for later steps:

Setup comwit
- uses: burrr-ai/comwit-cli@v0

The action reference (@v0) pins the action interface. The optional version input pins the CLI binary release; add with: { version: vX.Y.Z } only when an exact release is required.

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.

SettingDefault / variablePurpose
Token config file~/.config/comwit/config.jsonWhere 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.

List projects
comwit projects list

The command calls GET /v1/projects and returns the projects your cwt_ token can access.

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

Storage commands are available in comwit v0.1.7 and newer. Storage is a project-owned S3-compatible bucket. Create the resource before an app uses it; there is no bind-first command and no Comwit-specific SDK.

Storage commands
comwit storage create --project <project-id> --name <globally-unique-bucket>
comwit storage create --project <project-id> --name <bucket> --public
comwit storage list --project <project-id>
comwit storage get --project <project-id> --storage <storage-id>
comwit storage public enable --project <project-id> --storage <storage-id>
comwit storage public disable --project <project-id> --storage <storage-id>
comwit storage delete --project <project-id> --storage <storage-id>

create prints the storage_id, exact bucket name, S3 endpoint, lifecycle status, stable default domain, and public status. --location-hint apac is the current optional placement hint. Public activation is asynchronous; poll storage get until the public domain and TLS are active.

Delete requires an empty bucket. Object upload/download uses a standard S3 client rather than a CLI lifecycle command. See Create and connect Storage and Use the S3 API.

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 ./dist/brrrd
comwit apps builds --project <project-id> --app <app-id>
comwit apps logs --project <project-id> --app <app-id> --tail 100
comwit apps env list --project <project-id> --app <app-id>
comwit apps domains list --project <project-id> --app <app-id>
comwit apps delete --project <project-id> --app <app-id> --wait

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.

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
FlagRequiredPurpose
--projectyesProject that owns the app.
--appyesApp to deploy to.
--packageyesPrebuilt package file, or a brrrd output directory to archive and upload.
--hostnoHostname to serve this deployment on.
--env-refnoReference to the environment configuration to apply.
--max-concurrent-requestsnoCap on concurrent requests for the deployment.

Read recent runtime logs for a deployed app:

Read app logs
comwit apps logs --project <project-id> --app <app-id>
comwit apps logs --project <project-id> --app <app-id> --tail 50 --level error
comwit apps logs --project <project-id> --app <app-id> --since 30m --follow
comwit apps logs --project <project-id> --app <app-id> --json
FlagPurpose
--tailNumber of recent log rows to request. Defaults to 100.
--sinceRFC3339 timestamp or duration such as 30m.
--levelFilter by debug, info, warn, or error.
--buildFilter to a build id.
--routeFilter to a route or HTTP path.
--request-idFilter to a request id.
--jsonPrint each log record as JSON.
--followKeep polling for new log rows.

App env commands manage plain, non-secret runtime configuration:

App env commands
comwit apps env list --project <project-id> --app <app-id>
comwit apps env set --project <project-id> --app <app-id> LOG_LEVEL info
comwit apps env unset --project <project-id> --app <app-id> LOG_LEVEL

Values are stored as plain text today. Do not put durable secrets here unless you are intentionally accepting that caveat; see Environment variables.

Attach, finalize, list, and remove hostnames for a runtime app:

App hostname commands
comwit apps domains list --project <project-id> --app <app-id>
comwit apps domains add --project <project-id> --app <app-id> --domain app.example.com
comwit apps domains add --project <project-id> --app <app-id> --domain app.example.com --managed
comwit apps domains finalize --project <project-id> --app <app-id> --domain app.example.com
comwit apps domains remove --project <project-id> --app <app-id> --domain app.example.com

Use --managed when the hostname is the apex or subdomain of a Comwit-managed project domain and you want Comwit to write the DNS records automatically. Without it, the API returns the DNS records you publish at your own provider.

Delete a runtime app and its platform-owned runtime state:

Delete an app
comwit apps delete --project <project-id> --app <app-id>
comwit apps delete --project <project-id> --app <app-id> --wait

The API delete is re-entrant. --wait retries until the response reports complete: true or the CLI times out.

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
CommandWhat it does
domains addCreates a Route 53 public hosted zone through platform-api and prints the nameservers you must set at your current registrar.
domains checkAsks platform-api to resolve authoritative NS records and report whether the domain is managed.
domains deleteRemoves 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 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>
FlagUsed byPurpose
--namecreate, updateRecord name (e.g. www). Loaded from the existing record on update if omitted.
--typecreate, updateRecord type (e.g. CNAME). Loaded from the existing record on update if omitted.
--valuecreate, updateRecord value(s). Supplying one or more replaces the record values.
--ttlcreate, updateTime-to-live in seconds. Loaded from the existing record on update if omitted.
--recordupdate, deleteRecord id to target.

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

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

Database commands
comwit databases create --project <project-id> --name production
comwit databases create --project <project-id> --name production --from-file ./app.sqlite --token-out ./production.token
comwit databases create --project <project-id> --name production --from-dump ./dump.sql --token-out ./production.token
comwit databases import-dump --project <project-id> --name production --from-dump dump.sql
comwit databases list --project <project-id>
comwit databases execute --project <project-id> --database <database-id> --command "select 1 as ok;"
comwit databases execute --project <project-id> --database <database-id> --file ./query.sql --json
comwit databases token rotate --project <project-id> --database <database-id>
comwit databases delete --project <project-id> --database <database-id>
comwit databases restore-points list --project <project-id> --database <database-id>
comwit databases restore --project <project-id> --database <database-id> --at 2026-07-13T03:00:00Z --token-out ./restored.token --wait
comwit databases restore status --project <project-id> --database <database-id> --operation <operation-id>
comwit databases operation status --project <project-id> --database <database-id> --operation <operation-id> --wait
comwit databases aliases list --project <project-id> --database <database-id>
comwit databases aliases set --project <project-id> --database <database-id> --alias nightly --generation <generation-id>
comwit databases aliases delete --project <project-id> --database <database-id> --alias nightly

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. databases token rotate prints a fresh one-time connection token; copy it immediately because raw database tokens are not stored for later lookup.

databases create --from-file <path> creates a new database from a single SQLite file. The CLI checks the file locally (no -wal/-shm sidecar, SQLite header, PRAGMA integrity_check, PRAGMA foreign_key_check; skip with --skip-local-checks), streams it with an exact Content-Length, prints the one-time token before uploading (--token-out writes it with mode 0600), then waits until the database is ready. --no-wait returns after the upload is accepted and prints the databases operation status command to poll later; --idempotency-key <key> pins the create key so a retried invocation resumes the same operation. --from-dump <path> accepts a SQL dump instead: the CLI replays it into a temporary single-file SQLite database locally (keep it with --sqlite-out <path>) and then continues as --from-file. See Create and connect a database.

databases import-dump is the migration helper for SQL dumps. It creates a new database, prints database, url, and one-time token, then replays the dump through the new database’s public libSQL/Hrana endpoint. It never imports into an existing database and does not accept raw .db files; use databases create --from-file for those.

Common dump sources
wrangler d1 export <DB_NAME> --remote --output d1-dump.sql
sqlite3 source.db .dump > sqlite-dump.sql
turso db shell <database-name> .dump > turso-dump.sql

If replay fails, the CLI reports the failing statement index and deletes only the database it just created. Pass --keep-failed-db when you want to inspect the partial database instead.

databases execute is the remote SQL counterpart to wrangler d1 execute. Supply exactly one input:

FlagPurpose
--command <sql>Execute one inline SQLite statement.
--file <path>Execute a SQLite-compatible SQL text file. Raw .db files are rejected.
--jsonPrint only the stable platform API result envelope.
--remoteCompatibility no-op; Comwit execution is already remote.
--localUnsupported; the CLI does not embed a local database engine.

The CLI splits files with SQLite-aware parsing, so trigger bodies and semicolons inside quoted strings stay intact. A final semicolon is optional. Statements run in order; after the first failure, later statements are skipped. Failed or skipped results make the command exit non-zero.

If a file uses an explicit transaction, it must include its matching COMMIT. When otherwise-successful input leaves a transaction open, platform-api rolls it back and returns 422, so the CLI exits non-zero. Failed input also triggers conditional rollback cleanup when it leaves an explicit transaction open.

The command calls:

POST /v1/projects/{projectId}/databases/{databaseId}/query

The platform API mints the short-lived query token server-side and never returns it to the CLI. See Run SQL & query tokens for request and result behavior, limits, and direct API usage.

PITR always restores into a new sibling database; it never rewinds or replaces the source database. Start by listing recovery points and saved aliases:

List restore points
comwit databases restore-points list \
--project <project-id> \
--database <database-id>

Start a restore by selecting exactly one of --at, --generation, or --alias. --at accepts Unix milliseconds or an RFC3339 timestamp and rejects future timestamps:

Restore and wait for completion
comwit databases restore \
--project <project-id> \
--database <database-id> \
--at 2026-07-13T03:00:00Z \
--name "before migration" \
--token-out ./restored.token \
--wait

The restore response includes the new database’s one-time token. --token-out <path> stores it with mode 0600; if you lose the token, rotate the restored database’s token. Without --wait, poll the asynchronous operation explicitly:

Check a restore operation
comwit databases restore status \
--project <project-id> \
--database <source-database-id> \
--operation <operation-id> \
--wait

Polling controls only what the CLI displays. Comwit persists the exact restore operation binding and reconciles active operations after a platform-api restart, so completion does not depend on leaving the CLI or browser open. A failed restore leaves the new sibling database non-connectable with status failed.

Aliases give recovery points stable names:

Manage restore aliases
comwit databases aliases list --project <project-id> --database <database-id>
comwit databases aliases set --project <project-id> --database <database-id> --alias nightly --at 2026-07-13T03:00:00Z
comwit databases aliases set --project <project-id> --database <database-id> --alias release --generation <generation-id>
comwit databases aliases delete --project <project-id> --database <database-id> --alias nightly

Alias creation accepts exactly one of --at or --generation. A restore may select an alias with --alias <name>.

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
GET /v1/projects/{projectId}/databases
POST /v1/projects/{projectId}/databases
DELETE /v1/projects/{projectId}/databases/{databaseId}
POST /v1/projects/{projectId}/databases/{databaseId}/token/rotate
POST /v1/projects/{projectId}/databases/{databaseId}/query
GET /v1/projects/{projectId}/databases/{databaseId}/restore-points
POST /v1/projects/{projectId}/databases/{databaseId}/restore
GET /v1/projects/{projectId}/databases/{databaseId}/operations/{operationId}
POST /v1/projects/{projectId}/databases/{databaseId}/aliases/{alias}
DELETE /v1/projects/{projectId}/databases/{databaseId}/aliases/{alias}
GET /v1/projects/{projectId}/storages
POST /v1/projects/{projectId}/storages
GET /v1/projects/{projectId}/storages/{storageId}
DELETE /v1/projects/{projectId}/storages/{storageId}
PUT /v1/projects/{projectId}/storages/{storageId}/public-access
GET /v1/projects/{projectId}/apps
POST /v1/projects/{projectId}/apps
GET /v1/projects/{projectId}/apps/{appId}
DELETE /v1/projects/{projectId}/apps/{appId}
POST /v1/projects/{projectId}/apps/{appId}/deployments
GET /v1/projects/{projectId}/apps/{appId}/builds
GET /v1/projects/{projectId}/apps/{appId}/logs
GET /v1/projects/{projectId}/apps/{appId}/environment
PUT /v1/projects/{projectId}/apps/{appId}/environment/{key}
DELETE /v1/projects/{projectId}/apps/{appId}/environment/{key}
GET /v1/projects/{projectId}/apps/{appId}/domains
POST /v1/projects/{projectId}/apps/{appId}/domains
POST /v1/projects/{projectId}/apps/{appId}/domains/{domain}/finalize
DELETE /v1/projects/{projectId}/apps/{appId}/domains/{domain}
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 commandRoute
projects listGET /v1/projects
databases listGET /v1/projects/{projectId}/databases
databases createPOST /v1/projects/{projectId}/databases
databases import-dumpPOST /v1/projects/{projectId}/databases, then POST {database_url}/v3/pipeline
databases executePOST /v1/projects/{projectId}/databases/{databaseId}/query
databases deleteDELETE /v1/projects/{projectId}/databases/{databaseId}
databases token rotatePOST /v1/projects/{projectId}/databases/{databaseId}/token/rotate
databases restore-points listGET /v1/projects/{projectId}/databases/{databaseId}/restore-points
databases restorePOST /v1/projects/{projectId}/databases/{databaseId}/restore
databases create --from-filePOST /v1/projects/{projectId}/databases (with source + Idempotency-Key), PUT /v1/projects/{projectId}/databases/{databaseId}/operations/{operationId}/content, then GET .../operations/{operationId}
databases restore statusGET /v1/projects/{projectId}/databases/{databaseId}/operations/{operationId}
databases operation statusGET /v1/projects/{projectId}/databases/{databaseId}/operations/{operationId}
databases aliases listGET /v1/projects/{projectId}/databases/{databaseId}/restore-points
databases aliases setPOST /v1/projects/{projectId}/databases/{databaseId}/aliases/{alias}
databases aliases deleteDELETE /v1/projects/{projectId}/databases/{databaseId}/aliases/{alias}
storage listGET /v1/projects/{projectId}/storages
storage createPOST /v1/projects/{projectId}/storages
storage getGET /v1/projects/{projectId}/storages/{storageId}
storage public enable|disablePUT /v1/projects/{projectId}/storages/{storageId}/public-access
storage deleteDELETE /v1/projects/{projectId}/storages/{storageId}
apps listGET /v1/projects/{projectId}/apps
apps createPOST /v1/projects/{projectId}/apps
apps deleteDELETE /v1/projects/{projectId}/apps/{appId}
deployPOST /v1/projects/{projectId}/apps/{appId}/deployments
apps buildsGET /v1/projects/{projectId}/apps/{appId}/builds
apps logsGET /v1/projects/{projectId}/apps/{appId}/logs
apps env listGET /v1/projects/{projectId}/apps/{appId}/environment
apps env setPUT /v1/projects/{projectId}/apps/{appId}/environment/{key}
apps env unsetDELETE /v1/projects/{projectId}/apps/{appId}/environment/{key}
apps domains listGET /v1/projects/{projectId}/apps/{appId}/domains
apps domains addPOST /v1/projects/{projectId}/apps/{appId}/domains
apps domains finalizePOST /v1/projects/{projectId}/apps/{appId}/domains/{domain}/finalize
apps domains removeDELETE /v1/projects/{projectId}/apps/{appId}/domains/{domain}
domains listGET /v1/projects/{projectId}/domains
domains addPOST /v1/projects/{projectId}/domains
domains checkPOST /v1/projects/{projectId}/domains/{domain}/delegation-check
domains deleteDELETE /v1/projects/{projectId}/domains/{domain}
domains records listGET /v1/projects/{projectId}/domains/{domain}/records
domains records createPOST /v1/projects/{projectId}/domains/{domain}/records
domains records updatePUT /v1/projects/{projectId}/domains/{domain}/records/{recordId}
domains records deleteDELETE /v1/projects/{projectId}/domains/{domain}/records/{recordId}

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