Get started

Install

On Linux (glibc or musl) and macOS, amd64 or arm64:

curl -fsSL https://raw.githubusercontent.com/joaomnuno/coolship/main/scripts/install.sh | sh

The script downloads the release archive from GitHub Releases, checks its SHA-256 against the release's checksums.txt, installs coolship into $HOME/.local/bin, and prints the installed version plus a one-liner for your shell if that directory is not on PATH. It needs curl or wget, tar, and sha256sum or shasum; it never runs sudo (if you point it at a system directory it prints the command to run instead). Windows is not supported by the script; build from source or use WSL.

Overrides, as environment variables or flags (sh -s -- --version 0.3.0 --dir /opt/bin):

Build from source

Coolship needs Go 1.26 or newer, matching coolify-cli so code can move upstream. Newer toolchains build it unchanged.

git clone https://github.com/joaomnuno/coolship.git
cd coolship
scripts/build            # bin/coolship, version stamped from the nearest tag
bin/coolship --version

A plain go build -o coolship . also works and reports the Git revision it was built from. Every vX.Y.Z tag publishes a GitHub Release with archives for Linux, macOS, and Windows on amd64 and arm64, plus a checksums.txt.

Log in

Log in once. Coolship verifies the URL and token against the server, then stores them in the same file coolify-cli uses, so if you have already authenticated there, skip this step, and if you log in here, coolify-cli is logged in too.

$ coolship login
Coolify URL: https://coolify.example.com
Context name [coolify]: home
API token:
Logged in to home (https://coolify.example.com) as team Personal on Coolify 4.3.18, now the default
Saved to /home/you/.config/coolify/config.json

Create the token in Coolify under Keys & Tokens with the read, write, and deploy abilities. The token is never echoed and never accepted as a flag. For CI, either set COOLSHIP_URL and COOLSHIP_TOKEN (no login needed) or pipe the token: echo "$TOKEN" | coolship login --url … --name ci --token-stdin. See Credentials.

Link the repository

If the repository is already an application on Coolify, link binds it. If it is not on Coolify yet, init creates the application from the repository's public remote and binds it in one step.

cd my-app
coolship link          # bind to an existing application
coolship init          # or: create the application first, then bind

link walks the hierarchy, asking only when a choice is genuinely ambiguous:

Select project
> Personal
  Work

Arrow keys and Enter pick, typing filters a long list, and Esc cancels. The picker then gives way to the result:

Linked project in /home/you/my-app/coolship.toml
Application: fenix-bot (9f8e7d6c)
Environment: production
Project: Personal
Context: home

It writes a small, credential-free coolship.toml at the repository root. Commit it; see Project binding.

Deploy

coolship deploy

Coolship deploys the source and branch already configured in Coolify, submits exactly one deployment, and waits for that deployment to finish, streaming the server's build log to stderr when your token may read it. Interrupting the command stops local waiting only; the remote deployment continues, and its UUID is reported. --no-wait returns the queued UUID immediately, --force rebuilds without cache, and --timeout bounds the wait (default 10 minutes). See Deployments.

Read the logs

coolship logs
coolship logs --lines 500
coolship logs --follow

logs reads the application's runtime logs; --follow keeps polling snapshots and reports any gap it cannot rule out instead of hiding it. coolship open opens the application's public URL in your browser, or its Coolify page with --dashboard, and coolship status reports the current status and URL.