API, CLI and CI deploys

API tokens#

Create a token under Settings → API tokens: a Name, an expiry (Expires after a number of days, or Never expires) and the Scopes it may use. The token is shown once — copy it into your CI secrets. It acts as you, with your role in the organization, limited to its scopes. The list shows when each token was created and last used; Revoke token disables it at once.

The number of requests per minute depends on your plan.

REST API v1#

Base URL https://app.zefily.com/api/v1, with the token as a Bearer token:

curl -H "Authorization: Bearer $ZEFILY_TOKEN" https://app.zefily.com/api/v1/servers

Every write goes through the same checks as the panel (validation, plan limits, the audit log).

The zefily CLI#

Download the CLI for your system from https://dl.zefily.com/cli/ (zefily-linux-amd64, zefily-linux-arm64, zefily-darwin-arm64, zefily-windows-amd64.exe…). Set ZEFILY_TOKEN to your token:

zefily servers
zefily sites [server]
zefily deploy <domain|site-id> [--wait]
zefily rollback <domain|site-id> [--release YYYYMMDDhhmmss] [--wait]
zefily job <id> [--wait]
zefily jobs <server> [--type site.deploy]

--wait follows the job and exits with status 1 when it does not succeed, so a pipeline fails with the deploy.

Deploy from CI#

Use a token with sites:read, sites:deploy and jobs:read, stored as a CI secret.

GitHub Actions:

deploy:
  needs: test
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  steps:
    - name: Deploy
      env:
        ZEFILY_TOKEN: ${{ secrets.ZEFILY_TOKEN }}
      run: |
        curl -fsSLo zefily https://dl.zefily.com/cli/zefily-linux-amd64
        chmod +x zefily
        ./zefily deploy app.example.com --wait

GitLab CI:

deploy:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - curl -fsSLo zefily https://dl.zefily.com/cli/zefily-linux-amd64 && chmod +x zefily
    - ./zefily deploy app.example.com --wait

To be notified when deploys finish, add a webhook for the deploy finished event.