# Credentials

Where Coolship finds a Coolify URL and token, how it shares them with coolify-cli, and how CI supplies them.

URL: https://coolship.itrocas.com/docs/concepts/credentials

Coolship never asks you to authenticate twice. [`coolship login`](https://coolship.itrocas.com/docs/commands/login) writes, and every command reads, the Coolify CLI configuration:

* Unix and macOS: `~/.config/coolify/config.json`
* Windows: `%APPDATA%\coolify\config.json`

If you have already logged in with [`coolify-cli`](https://github.com/coollabsio/coolify-cli), Coolship uses that login; if you log in with Coolship, coolify-cli is logged in too. `--coolify-config PATH` reads an explicit file instead.

## Which instance is used

That file can hold several instances, called contexts. The one used for an invocation is selected by, in order:

1. `--context NAME` on the command line;
2. the `context` committed in `coolship.toml`;
3. the single default instance in the file.

A missing or ambiguous choice is an error rather than a guess. `coolship config` reports which credentials would be used, without making a request or showing the token.

## Tokens

Create a token in Coolify under *Keys & Tokens* with the read, write, and deploy abilities. `login` verifies the URL and token against the server (`GET /version` and the current team) before saving them. The token is read without echo, or from stdin with `--token-stdin`; it is never accepted as a flag, so it stays out of shell history and process listings.

Build logs and secret values can be withheld by token ability and team role. Coolship reports withheld data as unavailable, never as empty data: a deployment continues without its log, and a hidden variable value is noted rather than written as an empty string. Reading build logs during `deploy` needs a token that may read sensitive data.

`coolship logout NAME` removes a context from the file. The token remains valid on the server until you revoke it in Coolify.

## CI

Where Coolify CLI may not be installed, supply the pair as environment variables:

```bash
export COOLSHIP_URL=https://coolify.example.com
export COOLSHIP_TOKEN=…
coolship deploy
```

Both are required together, and the pair cannot be combined with `--context` or `--coolify-config`. It overrides any committed context for that invocation, and Coolship says so in a warning. The [CI guide](https://coolship.itrocas.com/docs/guides/ci) shows the GitHub Actions setup.

## What is never stored

Tokens and fetched secret values are never written to `coolship.toml`, to fixtures, or to debug output. Credential files are kept read-only, and the file Coolship writes on `login` is the same one coolify-cli manages.