Skip to content

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.

For macOS and Linux, use the checksum-verifying standalone installer:

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

The 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:

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

Run the npm package without installing it:

Run comwit with npx
npx comwit-cli version

You can tune the standalone installer with environment variables:

Installer environment variables
# Install a specific released version instead of the latest
curl -fsSL https://raw.githubusercontent.com/burrr-ai/comwit-cli/main/install.sh | COMWIT_VERSION=vX.Y.Z sh

For npm installs, update through npm:

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

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

Update comwit
comwit update

You can 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 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.

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:

Setup comwit in GitHub Actions
- uses: burrr-ai/comwit-cli@v0

See Deploy with GitHub Actions for a complete workflow.

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

Build from source
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

The CLI source lives in burrr-ai/comwit-cli.

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.

Run comwit login with no token to start the device authorization flow:

Sign in with device login
comwit login

What happens:

  1. The CLI requests a short code and opens your browser.
  2. 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.
  3. 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:

Device login and pin a project
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:

  1. Go to API tokens in the console at https://cloud.comwit.io/tokens.
  2. Create a token. The cwt_ plaintext is shown once at creation — copy it then.
  3. Hand it to the CLI:
Sign in with an existing token
comwit login --token cwt_xxx --project <project-id>

You can revoke a token any time from the same API tokens page.

The CLI stores your token and default project in a config file:

~/.config/comwit/config.json
{
"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:

VariablePurpose
COMWIT_CONFIGPath 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_PROJECTDefault project for commands that accept --project.

The CLI resolves the project for a command in this order:

  1. The --project flag.
  2. The COMWIT_PROJECT environment variable.
  3. The default_project saved in your config file.

The API host always defaults to https://api.cloud.comwit.io.

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:

Pin a default project at login
comwit login --project <project-id>

You can also pin it for a single shell session with the environment variable:

Override the project for one session
export COMWIT_PROJECT=<project-id>
comwit databases list

Once you’re signed in, list the databases in your project to confirm everything is wired up:

Smoke test
comwit databases list --project <project-id>

If you pinned a default project, you can drop the flag entirely:

Terminal window
comwit databases list

If you get a 403, the token’s scopes or your project membership don’t cover the action — see API authentication.