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.
Install
Section titled “Install”Recommended for macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | shcomwit versionThe npm package is the cross-platform mirror for macOS, Linux, and Windows:
npm install -g comwit-clicomwit versionRun the npm package without installing it:
npx comwit-cli versionThe 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:
curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | COMWIT_VERSION=vX.Y.Z sh| Variable | What it does |
|---|---|
COMWIT_VERSION | Pin the release tag to download instead of the latest. |
Build from source
Section titled “Build from source”If you want to build the CLI directly, use the public source repository:
git clone https://github.com/burrr-ai/comwit-cli.gitcd comwit-cligo test ./...go build -trimpath -o ./dist/comwit ./cmd/comwit./dist/comwit versionUpdate
Section titled “Update”For npm installs, update through npm:
npm install -g comwit-cli@latestFor standalone installs, update the current binary in place from the latest GitHub release:
comwit updatePin a release tag or repository when needed:
comwit update --version vX.Y.Zcomwit update --repo burrr-ai/comwit-clicomwit 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.
GitHub Actions
Section titled “GitHub Actions”Use the setup action when a GitHub Actions workflow needs comwit available for
later steps:
- uses: burrr-ai/comwit-cli@v0The 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.
Authentication
Section titled “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.
comwit login # device flow (recommended)comwit login --project <project-id>comwit login --token <token> # paste an existing PATcomwit 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.
Configuration and environment
Section titled “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
Section titled “Projects”comwit projects listThe 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
Section titled “Storage”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.
comwit storage create --project <project-id> --name <globally-unique-bucket>comwit storage create --project <project-id> --name <bucket> --publiccomwit 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
Section titled “Runtime apps”Runtime apps are the deployable services in a project. You list them, create them, push a deployment, and inspect builds.
comwit apps list --project <project-id>comwit apps create --project <project-id> --name webcomwit deploy --project <project-id> --app <app-id> --package ./dist/brrrdcomwit apps builds --project <project-id> --app <app-id>comwit apps logs --project <project-id> --app <app-id> --tail 100comwit 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> --waitDeploy
Section titled “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.
Deploy also accepts several 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. |
Read recent runtime logs for a deployed app:
comwit apps logs --project <project-id> --app <app-id>comwit apps logs --project <project-id> --app <app-id> --tail 50 --level errorcomwit apps logs --project <project-id> --app <app-id> --since 30m --followcomwit apps logs --project <project-id> --app <app-id> --json| Flag | Purpose |
|---|---|
--tail | Number of recent log rows to request. Defaults to 100. |
--since | RFC3339 timestamp or duration such as 30m. |
--level | Filter by debug, info, warn, or error. |
--build | Filter to a build id. |
--route | Filter to a route or HTTP path. |
--request-id | Filter to a request id. |
--json | Print each log record as JSON. |
--follow | Keep polling for new log rows. |
App environment
Section titled “App environment”App env commands manage plain, non-secret runtime configuration:
comwit apps env list --project <project-id> --app <app-id>comwit apps env set --project <project-id> --app <app-id> LOG_LEVEL infocomwit apps env unset --project <project-id> --app <app-id> LOG_LEVELValues are stored as plain text today. Do not put durable secrets here unless you are intentionally accepting that caveat; see Environment variables.
App hostnames
Section titled “App hostnames”Attach, finalize, list, and remove hostnames for a runtime app:
comwit apps domains list --project <project-id> --app <app-id>comwit apps domains add --project <project-id> --app <app-id> --domain app.example.comcomwit apps domains add --project <project-id> --app <app-id> --domain app.example.com --managedcomwit apps domains finalize --project <project-id> --app <app-id> --domain app.example.comcomwit apps domains remove --project <project-id> --app <app-id> --domain app.example.comUse --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 an app
Section titled “Delete an app”Delete a runtime app and its platform-owned runtime state:
comwit apps delete --project <project-id> --app <app-id>comwit apps delete --project <project-id> --app <app-id> --waitThe API delete is re-entrant. --wait retries until the response reports
complete: true or the CLI times out.
Domains
Section titled “Domains”Project-domain commands manage delegated DNS through the platform API using your
cwt_ token. The CLI never calls AWS directly.
comwit domains list --project <project-id>comwit domains add --project <project-id> --domain example.comcomwit domains check --project <project-id> --domain example.comcomwit 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
Section titled “DNS records”DNS record management uses nested commands under domains records.
comwit domains records list --project <project-id> --domain example.comcomwit domains records create \ --project <project-id> \ --domain example.com \ --name www \ --type CNAME \ --value target.example.net \ --ttl 300comwit domains records update \ --project <project-id> \ --domain example.com \ --record <record-id> \ --value target2.example.net \ --ttl 300comwit domains records delete \ --project <project-id> \ --domain example.com \ --record <record-id>Record flags
Section titled “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
Section titled “Scopes and locking”Required scopes are domain:read for list and read operations, and
domain:write for add, check, create, update, and delete.
Domain purchase is not in the CLI
Section titled “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.
Databases
Section titled “Databases”comwit databases create --project <project-id> --name productioncomwit databases create --project <project-id> --name production --from-file ./app.sqlite --token-out ./production.tokencomwit databases create --project <project-id> --name production --from-dump ./dump.sql --token-out ./production.tokencomwit databases import-dump --project <project-id> --name production --from-dump dump.sqlcomwit 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 --jsoncomwit 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 --waitcomwit 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> --waitcomwit 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 nightlyThese 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.
wrangler d1 export <DB_NAME> --remote --output d1-dump.sqlsqlite3 source.db .dump > sqlite-dump.sqlturso db shell <database-name> .dump > turso-dump.sqlIf 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.
Execute remote SQL
Section titled “Execute remote SQL”databases execute is the remote SQL counterpart to wrangler d1 execute.
Supply exactly one input:
| Flag | Purpose |
|---|---|
--command <sql> | Execute one inline SQLite statement. |
--file <path> | Execute a SQLite-compatible SQL text file. Raw .db files are rejected. |
--json | Print only the stable platform API result envelope. |
--remote | Compatibility no-op; Comwit execution is already remote. |
--local | Unsupported; 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}/queryThe 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.
Restore with PITR
Section titled “Restore with PITR”PITR always restores into a new sibling database; it never rewinds or replaces the source database. Start by listing recovery points and saved aliases:
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:
comwit databases restore \ --project <project-id> \ --database <database-id> \ --at 2026-07-13T03:00:00Z \ --name "before migration" \ --token-out ./restored.token \ --waitThe 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:
comwit databases restore status \ --project <project-id> \ --database <source-database-id> \ --operation <operation-id> \ --waitPolling 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:
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:00Zcomwit 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 nightlyAlias creation accepts exactly one of --at or --generation. A restore may
select an alias with --alias <name>.
API routes used by the CLI
Section titled “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:
GET /v1/projectsGET /v1/projects/{projectId}/databasesPOST /v1/projects/{projectId}/databasesDELETE /v1/projects/{projectId}/databases/{databaseId}POST /v1/projects/{projectId}/databases/{databaseId}/token/rotatePOST /v1/projects/{projectId}/databases/{databaseId}/queryGET /v1/projects/{projectId}/databases/{databaseId}/restore-pointsPOST /v1/projects/{projectId}/databases/{databaseId}/restoreGET /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}/storagesPOST /v1/projects/{projectId}/storagesGET /v1/projects/{projectId}/storages/{storageId}DELETE /v1/projects/{projectId}/storages/{storageId}PUT /v1/projects/{projectId}/storages/{storageId}/public-accessGET /v1/projects/{projectId}/appsPOST /v1/projects/{projectId}/appsGET /v1/projects/{projectId}/apps/{appId}DELETE /v1/projects/{projectId}/apps/{appId}POST /v1/projects/{projectId}/apps/{appId}/deploymentsGET /v1/projects/{projectId}/apps/{appId}/buildsGET /v1/projects/{projectId}/apps/{appId}/logsGET /v1/projects/{projectId}/apps/{appId}/environmentPUT /v1/projects/{projectId}/apps/{appId}/environment/{key}DELETE /v1/projects/{projectId}/apps/{appId}/environment/{key}GET /v1/projects/{projectId}/apps/{appId}/domainsPOST /v1/projects/{projectId}/apps/{appId}/domainsPOST /v1/projects/{projectId}/apps/{appId}/domains/{domain}/finalizeDELETE /v1/projects/{projectId}/apps/{appId}/domains/{domain}GET /v1/projects/{projectId}/domainsPOST /v1/projects/{projectId}/domainsGET /v1/projects/{projectId}/domains/{domain}DELETE /v1/projects/{projectId}/domains/{domain}POST /v1/projects/{projectId}/domains/{domain}/delegation-checkGET /v1/projects/{projectId}/domains/{domain}/recordsPOST /v1/projects/{projectId}/domains/{domain}/recordsPUT /v1/projects/{projectId}/domains/{domain}/records/{recordId}DELETE /v1/projects/{projectId}/domains/{domain}/records/{recordId}| CLI command | Route |
|---|---|
projects list | GET /v1/projects |
databases list | GET /v1/projects/{projectId}/databases |
databases create | POST /v1/projects/{projectId}/databases |
databases import-dump | POST /v1/projects/{projectId}/databases, then POST {database_url}/v3/pipeline |
databases execute | POST /v1/projects/{projectId}/databases/{databaseId}/query |
databases delete | DELETE /v1/projects/{projectId}/databases/{databaseId} |
databases token rotate | POST /v1/projects/{projectId}/databases/{databaseId}/token/rotate |
databases restore-points list | GET /v1/projects/{projectId}/databases/{databaseId}/restore-points |
databases restore | POST /v1/projects/{projectId}/databases/{databaseId}/restore |
databases create --from-file | POST /v1/projects/{projectId}/databases (with source + Idempotency-Key), PUT /v1/projects/{projectId}/databases/{databaseId}/operations/{operationId}/content, then GET .../operations/{operationId} |
databases restore status | GET /v1/projects/{projectId}/databases/{databaseId}/operations/{operationId} |
databases operation status | GET /v1/projects/{projectId}/databases/{databaseId}/operations/{operationId} |
databases aliases list | GET /v1/projects/{projectId}/databases/{databaseId}/restore-points |
databases aliases set | POST /v1/projects/{projectId}/databases/{databaseId}/aliases/{alias} |
databases aliases delete | DELETE /v1/projects/{projectId}/databases/{databaseId}/aliases/{alias} |
storage list | GET /v1/projects/{projectId}/storages |
storage create | POST /v1/projects/{projectId}/storages |
storage get | GET /v1/projects/{projectId}/storages/{storageId} |
storage public enable|disable | PUT /v1/projects/{projectId}/storages/{storageId}/public-access |
storage delete | DELETE /v1/projects/{projectId}/storages/{storageId} |
apps list | GET /v1/projects/{projectId}/apps |
apps create | POST /v1/projects/{projectId}/apps |
apps delete | DELETE /v1/projects/{projectId}/apps/{appId} |
deploy | POST /v1/projects/{projectId}/apps/{appId}/deployments |
apps builds | GET /v1/projects/{projectId}/apps/{appId}/builds |
apps logs | GET /v1/projects/{projectId}/apps/{appId}/logs |
apps env list | GET /v1/projects/{projectId}/apps/{appId}/environment |
apps env set | PUT /v1/projects/{projectId}/apps/{appId}/environment/{key} |
apps env unset | DELETE /v1/projects/{projectId}/apps/{appId}/environment/{key} |
apps domains list | GET /v1/projects/{projectId}/apps/{appId}/domains |
apps domains add | POST /v1/projects/{projectId}/apps/{appId}/domains |
apps domains finalize | POST /v1/projects/{projectId}/apps/{appId}/domains/{domain}/finalize |
apps domains remove | DELETE /v1/projects/{projectId}/apps/{appId}/domains/{domain} |
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} |
For more on the API itself, see the API overview and Authentication.