# Get started Install Coolship, log in to your Coolify instance, link a repository, deploy it, and read its logs. URL: https://coolship.itrocas.com/docs/get-started This walk-through takes about five minutes. You need a Coolify instance you can reach, an API token for it, and a repository that is (or will be) an application on that instance. ## Install On Linux (glibc or musl) and macOS, amd64 or arm64: ```bash 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`): | Variable | Flag | Default | Meaning | | ---------------------- | ----------- | ------------------ | -------------------------------------------------------------------- | | `COOLSHIP_VERSION` | `--version` | latest | Release to install; a pre-release such as `0.3.0-rc.1` must be named | | `COOLSHIP_INSTALL_DIR` | `--dir` | `$HOME/.local/bin` | Directory to install into, created if missing | | | `--dry-run` | | Resolve the version and print what would happen | ### Build from source Coolship needs Go 1.26 or newer, matching `coolify-cli` so code can move upstream. Newer toolchains build it unchanged. ```bash 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](https://github.com/joaomnuno/coolship/releases) 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`](https://github.com/coollabsio/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. ```text $ 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](https://coolship.itrocas.com/docs/concepts/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. ```bash 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: ```text 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: ```text 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](https://coolship.itrocas.com/docs/concepts/project-binding). > **Private repositories and build packs** > A public repository is cloned without credentials. A private one is created through a GitHub App or a deploy key registered in Coolify; `init` asks which, or takes `--github-app`, `--deploy-key`, or `--create-deploy-key`. The build pack is detected from the application root (Compose file, Dockerfile, plain HTML, or Railpack for anything else) and refined with the flags in the [init reference](https://coolship.itrocas.com/docs/commands/init). ## Deploy ```bash 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](https://coolship.itrocas.com/docs/concepts/deployments). ## Read the logs ```bash 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. ## Next steps - [Check the setup](https://coolship.itrocas.com/docs/commands/doctor): `doctor` runs every step a command performs and reports each one. - [Sync environment variables](https://coolship.itrocas.com/docs/guides/environment-variables): Pull, diff, and push a `.env` file against one scope of the application's variables. - [Deploy from CI](https://coolship.itrocas.com/docs/guides/ci): Use `COOLSHIP_URL` and `COOLSHIP_TOKEN` in GitHub Actions, and deploy pull-request previews. - [Monorepos](https://coolship.itrocas.com/docs/guides/monorepos): Bind several applications in one repository with named targets.