# Coolify Tooling

All commands assume PowerShell from the project root.

> **Canonical catalog:** [`docs/TOOL-INDEX.md`](../docs/TOOL-INDEX.md). This file
> holds usage examples; the index holds verified signatures, env requirements,
> read-only/mutating classification and the gotchas. Read its §1 first.

## Two gotchas specific to this wrapper

**1. `-Raw` is inverted.** `Invoke-CoolifyApi.ps1` returns a **JSON string** by
default and **PowerShell objects with `-Raw`**. Filtering the default output
silently yields nothing — no error:

```powershell
# WRONG: $r is a System.String, so this prints an empty row
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" | Select-Object name, uuid

# RIGHT
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" -Raw | Select-Object name, uuid
```

**2. `/applications/*` 404s through the public hostname — that block is
Cloudflare's, not Coolify's** (re-verified 2026-08-29 on v4.3.14: same token,
same route → 200 against the origin `http://192.168.0.117:8000/api/v1`, 404 via
`https://coolify.urieljareth.org`). For those endpoints use
`$env:COOLIFY_API_URL_ORIGIN`. Also: state-changing endpoints are POST-only
since v4.2 (`GET /deploy` → 405). Endpoints that work through either path:
`/version`, `/resources`, `/services`, `/databases`, `/projects`, `/servers`,
`/teams`, `/deployments`. Use `/resources` to enumerate apps.

## Environment

Load private values from an ignored local file:

```powershell
. .\.env.local.ps1
```

Expected variables:

```powershell
$env:COOLIFY_API_URL = "https://coolify.urieljareth.org/api/v1"
$env:COOLIFY_TOKEN = "REPLACE_WITH_TOKEN"
```

## Read-Only Diagnostics

```powershell
.\scripts\Test-ProxmoxConnection.ps1
.\coolify_skill\scripts\Get-CoolifyDockerStatus.ps1 -All
.\coolify_skill\scripts\Get-CoolifyDockerStatus.ps1 -Filter "coolify|cloudflared|nextcloud|postgres|redis"
```

```powershell
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker stats --no-stream"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker network ls"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker volume ls"
```

## A New Service Is Green In Coolify But Its Domain Returns 503

Coolify's green dot means the container is `running`. Traefik only routes a
container Docker reports `healthy`. A brand-new service is `running` long before
it is `healthy`, so its route does not exist yet and the request falls through to
Coolify's catch-all (`noop` service, empty server list) — which is what prints
`no available server`.

```powershell
# Contrast running vs healthy, flag a too-short start_period, probe the domain.
.\coolify_skill\scripts\Test-CoolifyServiceReady.ps1 -Uuid <resource-uuid>

# First boot on this host can take minutes (HDD-backed loopback rootfs). Wait it out.
.\coolify_skill\scripts\Test-CoolifyServiceReady.ps1 -Uuid <resource-uuid> -WaitSeconds 600
```

Read the status code before changing anything:

- `502 Bad Gateway` — the route exists, the backend refuses. App or port problem.
- `503 no available server` — there is no route. Usually still starting.
  **Do not redeploy**: that restarts the entrypoint from scratch and restarts the
  slow boot. See TOOL-INDEX.md 1.5.

## Logs And Inspect

```powershell
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker logs <container> --tail 100"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker inspect <container>"
```

## Coolify API

Verified working on this instance (2026-08-07):

```powershell
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/version"
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources"    # 28 — the app inventory
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/projects"     # 7
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/services"     # 14
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/databases"    # 5
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/servers"      # 1
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/teams"        # 1
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/deployments"  # in-flight deploys
```

**`/applications` and its whole namespace 404 through the public hostname
(Cloudflare edge block) but work via the origin** — point
`COOLIFY_API_URL` at `http://192.168.0.117:8000/api/v1` for those calls. Either
way, to enumerate applications and resolve a name or uuid, `/resources` is the
reliable inventory:

```powershell
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" -Raw |
    Where-Object { $_.name -match 'chatwoot' } | Select-Object name, uuid, fqdn
```

### Resolving a container name from a resource

Container names are `<service>-<uuid>` plus an optional build suffix, so they are
not guessable and **change when a redeploy recreates the container**:

```powershell
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker ps --format '{{.Names}}' | grep -i <app>"
```

For write calls, prepare the JSON body first and ask for confirmation:

```powershell
$body = @{ name = "example" } | ConvertTo-Json -Depth 20
.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Method POST -Path "/projects" -BodyJson $body
```

## API Reference Search

```powershell
rg -n "applications|deploy|database|environment" .\coolify_skill\references
Get-Content .\coolify_skill\references\ops\list-applications.md
Get-Content .\coolify_skill\references\ops\deploy-by-tag-or-uuid.md
```

## Commands That Require Confirmation

- Coolify deploys and API writes: `POST`, `PUT`, `PATCH`, `DELETE`.
- Docker lifecycle: `restart`, `stop`, `rm`, `compose up`, `compose down`.
- Environment variable writes or full env exports.
- Key, token, SSH, domain, proxy, server, network, or volume changes.