The CLI

apps/cli is published to npm as @keelhosting/cli (binary keel). It is one client of the public API described in HTTP API: every command maps onto the generated @keel/api-client, nothing reaches the database or an internal service. The bundle is a single ESM file (dist/keel.js, built with esbuild) plus @napi-rs/keyring for the OS keychain.

npm install -g @keelhosting/cli
keel login
keel init
keel deploy
keel run --follow

Global flags

Output conventions: results go to stdout, progress (docker output, build logs, sync notes) goes to stderr, errors are one line on stderr prefixed keel:. Secrets, registry passwords and tokens are never printed.

Configuration and credentials

The config file lives at $KEEL_CONFIG_DIR/config.json, else $XDG_CONFIG_HOME/keel/config.json, else ~/Library/Application Support/keel/config.json on macOS, %APPDATA%\keel\config.json on Windows and ~/.config/keel/config.json elsewhere. It is written with mode 0600 and holds profiles only:

{
  "version": 1,
  "profiles": {
    "default": { "apiUrl": "https://api.keelhosting.dev", "issuer": "https://auth.keelhosting.dev", "clientId": "…", "projectId": "…", "defaultOrg": "acme" }
  }
}

Tokens never touch the file. keel login stores { accessToken, refreshToken, expiresAt, issuer, clientId, scope } in the OS keychain under service keel, account <profile> (@napi-rs/keyring: macOS Keychain, Windows Credential Manager, Secret Service or keyutils on Linux). An expired access token is refreshed with the OIDC refresh grant before the request; a 401 from the API triggers one refresh and one retry, then the session is cleared and the command exits 3 with run keel login. A rejected API key exits 3 without touching the keychain.

Exit codes

Commands

Session

Project

keel.yaml:

name: Invoice Reconciler
slug: invoice-reconciler
mode: run
build:
  dockerfile: Dockerfile
  context: .
  platform: linux/arm64
  runtime: node
  packageManager: pnpm
  buildCommand: pnpm run build
  startCommand: node dist/server.js
  nodeVersion: 22
process:
  command: ["node", "agent.mjs"]
resources:
  cpu: 512
  memoryMb: 1024
  ephemeralStorageGb: 20
limits:
  wallClockSeconds: 600
  maxSteps: 200
  maxTotalSeconds: 600
egress:
  customHosts:
    - erp.internal.example
    - host: files.example.com
      mode: tunnel
env:
  LOG_LEVEL: info
secrets:
  - OPENAI_API_KEY
  - name: erp-token
    env: ERP_TOKEN
capabilities:
  checkpoints: false
trace:
  capture: full
workspace:
  mountPath: /keel/workspace
  sizeGb: 1
ingress:
  port: 8080
service:
  kind: agent
  replicas: 2
  healthCheck:
    path: /healthz
    intervalSeconds: 10
    timeoutSeconds: 5
    unhealthyThreshold: 3
    startPeriodSeconds: 30
trigger:
  kind: schedule
  schedule: { expression: "*/15 * * * *", timezone: Europe/Berlin }
triggers:
  - kind: webhook
callbackUrl: https://app.example.com/hooks/keel

Everything except name and slug is optional. build.dockerfile has no default any more: when it is absent and the context has no Dockerfile, keel deploy generates one from the detected runtime, and build.runtime, packageManager, buildCommand, startCommand, nodeVersion, pythonVersion and goVersion steer that detection (Builds without a Dockerfile). The generated image listens on ingress.port (default 8080) through PORT. Values the file omits come from the manifest the platform derives from the plan (defaultManifestForPlan), or from the agent's latest revision once one exists. mode is run (default) or service; a service is kept up by the platform, restarted when it crashes and billed per replica-month, pro-rated by the hour. service.kind says what the service is and therefore what a replica costs: agent (default; an AI agent or bot, 49 EUR per replica-month on Business and Enterprise) or app (a regular backend such as an API, a web app or a worker, 19 EUR per replica-month). The api-node, api-python and api-go templates write kind: app, the bot and webhook-bot templates kind: agent. The kind lives on the agent (serviceKind on POST /v1/agents and PATCH /v1/agents/{id}), not in the runtime manifest, so changing it needs no new image; when the file declares service.kind, keel deploy aligns the agent with it before building and stops with a usage error (exit 2, no revision created) when the service is running with another kind (409 service_kind_locked), because a kind change only takes effect while the service is stopped: keel service stop <slug>, deploy, keel service start <slug>. A file without service.kind leaves the agent's kind alone (a new agent starts as agent), so a kind chosen in the dashboard survives deploys from a file that does not mention it. workspace mounts a persistent volume at mountPath (default /keel/workspace) of sizeGb (at most the plan's workspaceGbPerAgent); ingress gives the service a public https hostname that forwards to port. Both need the services (and ingress) plan features; both are kept from the previous revision when the file omits them and removed with an explicit workspace: null or ingress: null. service also sets the replica count of a service (replicas, default 1, clamped to the plan's maxReplicasPerService, each replica billed at the kind's price) and an HTTP healthCheck the supervisor probes on the agent container (path is required; port defaults to the ingress port and is required without ingress; the other fields default to the values shown). With a health check a replica only receives traffic once a probe passed, and it is restarted after unhealthyThreshold consecutive misses; without one, an ingress replica is ready when its port accepts a TCP connection. keel service scale overrides replicas without a new revision. See Services and APIs.

keel deploy does, in order:

1. Reads keel.yaml and ensures the agent exists (GET /v1/agents by slug, POST /v1/agents when missing, with callbackUrl as the default callback and the file's mode). An existing agent whose mode differs is switched with PATCH /v1/agents/{id}; that is refused (409 mode_change_blocked, exit 5) while a run is active or the service is running.
2. Gets an image registered:
   • --image <ref>: POST /v1/agents/{id}/images with createRevision: false and a reference inside the tenant repository; the answer carries the resolved image.digest and repository.
   • default: resolves the Dockerfile (build.dockerfile, else <context>/Dockerfile, else one generated into a temporary directory next to a Dockerfile.keel.dockerignore when the context has no .dockerignore; the temporary directory is removed after the push), POST /v1/registry/push-credentials, then docker build --tag <repositoryUri>:<tag> --file <dockerfile> [--platform <platform>] <context>, docker login <registry> --username <user> --password-stdin (the password only travels on stdin), docker push, then docker logout <registry> whether or not the push succeeded so the short-lived credential does not linger in the Docker credential store, the digest is parsed from the push output and POST /v1/agents/{id}/images registers <repositoryUri>@<digest> without a revision. Docker output streams to stderr.
   • --via-build: POST /v1/agents/{id}/builds from the connected repository, follows GET /v1/builds/{id}/logs until GET /v1/builds/{id} is terminal. The read is passive: the API's build poller (REAPER=inprocess locally, the worker in production) is what moves the build along, so a deployment without a poller never finishes.
3. Assembles the runtime manifest from keel.yaml on top of a base: the agent's latest revision when it has one, otherwise the plan defaults from GET /v1/organizations/me/plan (defaultManifestForPlan with the plan limits, features and the current verified endpoint list version). It validates the result with runtimeManifestSchema and calls POST /v1/agents/{id}/revisions, so one keel deploy produces exactly one revision. Fields the plan clamped are reported (resources.memoryMb clamped by the plan from 4096 to 1024).
4. Syncs the triggers declared in the file: one trigger per declared kind is created, updated (schedule or enabled flag) or left alone. A new webhook trigger prints its secret once.
5. Prints the revision id and the egress summary: Egress: deny-all, allowlist v12, 1 custom host. The --json document carries detectedRuntime (node 22, python 3.12 (fastapi), go 1.23, or null when a Dockerfile was used). For a service agent it adds one line: a running service is restarted by the platform on the new revision (a rolling restart, watch it with keel service status <slug> --follow), a stopped one needs keel service start. The --json document carries agent.mode, agent.serviceKind, agent.serviceKindChanged and service: { state, rollingRestart }; the progress line names the kind (created agent orders-api (...) in service mode as app, now billed as app).

Runs

Services and ingress

Static sites

[site] defaults to site.slug in keel.yaml. keel init --template static scaffolds a site project. Details in Static sites.

Agents, secrets, triggers, keys, usage

Data stores (keel db)

Managed Postgres and Valkey on plans that include data stores (data_stores_not_in_plan is 409, exit 5). Every store injects its connection URL as an organization secret; the CLI never prints a URL except from keel db url.

Secret naming: the name is a lowercase slug of at most 32 characters (letters, digits and hyphens, starting and ending with a letter or digit). A store named main becomes DATABASE_URL (Postgres) or REDIS_URL (Valkey); any other name is upper-cased with hyphens turned into underscores and prefixed, so job-queue becomes JOB_QUEUE_DATABASE_URL or JOB_QUEUE_REDIS_URL. Add that name under secrets: in keel.yaml and deploy; the generated keel.yaml carries a reminder comment above secrets:.

There is no keel db psql. Stores have no public port, so an interactive shell would need a tunnel, which is not offered. Use keel db url from a service that runs inside the platform, or a one-off keel run that reads the secret from its environment.

CI

- run: npm install -g @keelhosting/cli
- run: keel deploy --image $ECR/keel-tenants/$ORG:$GITHUB_SHA --json > revision.json
  env:
    KEEL_API_KEY: ${{ secrets.KEEL_API_KEY }}
    KEEL_API_URL: https://api.keelhosting.dev
- run: keel run --follow --json > run.json
  env:
    KEEL_API_KEY: ${{ secrets.KEEL_API_KEY }}

Keys come from keel api-keys create ci --scope agents:write runs:trigger builds:write secrets:write (scopes in HTTP API). API keys cannot manage the organization, members or other keys. The key belongs to one organization, so --org is unnecessary.

Development

pnpm --filter keel build       # tsc -b, then esbuild to dist/keel.js
pnpm --filter keel test        # unit tests plus the in-process API suite
node apps/cli/dist/keel.js --help

apps/cli/test/integration.spec.ts boots the real API with the in-memory ports (apps/api/test/support/test-app.ts), a fake OIDC issuer for the device flow, an in-memory keychain, a recording browser opener and a fake docker, and drives runCli directly. test/package.spec.ts runs pnpm pack --dry-run and asserts the tarball holds only dist/keel.js, README.md and package.json.

Known gaps

• GET /v1/agents has no slug filter, so slug resolution pages through the list.
• Whether the local registry:2 accepts docker login with the placeholder credentials the API returns for IMAGE_BUILDER=local was not verified in this change.
• The refresh grant assumes the keel-cli application in Zitadel has refresh tokens enabled for the device grant; zitadel-bootstrap.ts was not changed here.