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

The simplest way to get comwit is the install script:

Install comwit

scripts/install-comwit.sh

This installs the binary to ~/.local/bin/comwit. Make sure ~/.local/bin is on your PATH so you can run comwit from anywhere.

How the installer chooses a binary

The installer first tries to download a published GitHub release asset named like comwit_<os>_<arch>.tar.gz (for example comwit_darwin_arm64.tar.gz). Until releases exist for your platform, it automatically falls back to building the CLI from the current checkout.

Installer options

You can tune the installer with environment variables:

Installer environment variables

# Install a specific released version instead of the latest
COMWIT_VERSION=v0.1.0 scripts/install-comwit.sh

# Install to a different directory (default is ~/.local/bin)
COMWIT_INSTALL_DIR=/usr/local/bin scripts/install-comwit.sh

# Pull release assets from a specific GitHub repository
COMWIT_INSTALL_REPO=comwit/comwit-cloud scripts/install-comwit.sh

Build it yourself

If you are working from a checkout of the repository and want to build the CLI directly, use the just recipes:

Build from source

just cli-test     # run the CLI test suite
just cli-build    # build the binary into ./dist
./dist/comwit version

The CLI source lives in tools/comwit.

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.

PLATFORM_API_SERVER_TOKEN is not your token

PLATFORM_API_SERVER_TOKEN is an internal server/operator token used by the console itself. It bypasses scope and membership checks and is not a user token. Never put it in your CLI config, scripts, or issue reports. Your token always starts with cwt_.

Option A — device login (recommended)

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. You approve the code while signed in to the console at https://cloud.comwit.io.
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

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.

Scopes

A cwt_ token only does what its scopes allow (for example database:read, app:deploy, domain:write) and can only touch projects you can access. Actions outside your scope or on a project you are not a member of return 403. See API authentication for the full scope table.

Configuration and environment

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:

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:

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.

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:

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

Verify it works

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:

comwit databases list

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

Next steps

• Create your first database
• Deploy an app
• Connect a domain
• CLI reference