Install the CLI & sign in
comwit is the command-line tool for Comwit Cloud. You use it to create
databases, deploy apps, and manage domains from your terminal. Under the hood it
only talks to the public platform API at https://api.cloud.comwit.io — it never
touches your cloud provider, the database server, or the runtime fleet directly.
This page gets you from nothing to a signed-in CLI. You will install the binary,
sign in to get a token, and (optionally) pin a default project so you can stop
typing --project on every command.
Install the CLI
Section titled “Install the CLI”For macOS and Linux, use the checksum-verifying standalone installer:
curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | shcomwit versionThe installer downloads the latest public release from
burrr-ai/comwit-cli, verifies its
checksum, and installs the binary to /usr/local/bin/comwit when possible,
falling back to ~/.local/bin/comwit. Make sure the installed directory is on
your PATH.
The npm package is the cross-platform mirror for macOS, Linux, and Windows on
amd64/arm64:
npm install -g comwit-clicomwit versionRun the npm package without installing it:
npx comwit-cli versionInstaller options
Section titled “Installer options”You can tune the standalone installer with environment variables:
# Install a specific released version instead of the latestcurl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | COMWIT_VERSION=vX.Y.Z shUpdate the CLI later
Section titled “Update the CLI later”For npm installs, update through npm:
npm install -g comwit-cli@latestFor standalone installs, update in place from the latest GitHub release:
comwit updateYou can pin a release tag or repository when needed:
comwit update --version vX.Y.Zcomwit update --repo burrr-ai/comwit-clicomwit update detects your current OS and architecture, downloads the matching
release asset such as comwit_darwin_arm64.tar.gz, and atomically replaces the
currently 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.
GitHub Actions
Section titled “GitHub Actions”In GitHub Actions, use the setup action instead of piping the install script in
a run step. It installs comwit and adds it to PATH for the rest of the job:
- uses: burrr-ai/comwit-cli@v0See Deploy with GitHub Actions for a complete workflow.
Build it yourself
Section titled “Build it yourself”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 versionThe CLI source lives in
burrr-ai/comwit-cli.
Sign in
Section titled “Sign in”Every command authenticates to the platform API with a bearer token. As an end
user you always use a cwt_ personal access token — a scoped token tied to
your user that can only act on projects you are a member of. There are two ways
to get signed in.
Option A — device login (recommended)
Section titled “Option A — device login (recommended)”Run comwit login with no token to start the device authorization flow:
comwit loginWhat happens:
- The CLI requests a short code and opens your browser.
- On the console’s CLI sign-in page at Comwit Cloud, paste the terminal’s code if it is not already filled and select Check code. Compare the displayed code with your terminal, review the organization and permissions, then select Approve this device. Checking the code alone does not grant access. Installation and command help is under Installation & commands.
- The CLI receives your
cwt_token and saves it to your config file.
That’s it — no copying and pasting tokens. You can pin a default project at the same time:
comwit login --project <project-id>Option B — dashboard personal access token
Section titled “Option B — dashboard personal access token”If you’d rather create the token yourself (for example for CI, or to control its scopes), generate one from the console:
- Go to API tokens in the console at https://cloud.comwit.io/tokens.
- Create a token. The
cwt_plaintext is shown once at creation — copy it then. - Hand it to the CLI:
comwit login --token cwt_xxx --project <project-id>You can revoke a token any time from the same API tokens page.
Configuration and environment
Section titled “Configuration and environment”The CLI stores your token and default project in a config file:
{ "token": "cwt_...", "default_project": "<project-id>"}You can influence where the CLI reads its token, which project it targets, and which API it calls with environment variables:
| Variable | Purpose |
|---|---|
COMWIT_CONFIG | Path to the config file. If unset, the CLI uses $XDG_CONFIG_HOME/comwit/config.json when XDG_CONFIG_HOME is set, otherwise ~/.config/comwit/config.json. |
COMWIT_PROJECT | Default project for commands that accept --project. |
The CLI resolves the project for a command in this order:
- The
--projectflag. - The
COMWIT_PROJECTenvironment variable. - The
default_projectsaved in your config file.
The API host always defaults to https://api.cloud.comwit.io.
Pin a default project
Section titled “Pin a default project”If most of your work happens in one project, pin it once so you can drop the
--project flag from individual commands. The easiest way is during login:
comwit login --project <project-id>You can also pin it for a single shell session with the environment variable:
export COMWIT_PROJECT=<project-id>comwit databases listVerify it works
Section titled “Verify it works”Once you’re signed in, list the databases in your project to confirm everything is wired up:
comwit databases list --project <project-id>If you pinned a default project, you can drop the flag entirely:
comwit databases listIf you get a 403, the token’s scopes or your project membership don’t cover
the action — see API authentication.