CLI

The lucity command line tool deploys services, checks on rollouts, and manages variables and databases, from your terminal or a CI pipeline. It also runs the MCP server that gives AI agents access to your projects, which Claude plugin & MCP covers.

Install

brew install --cask zeitlos/tap/lucity

VERSION=$(curl -fsSL https://api.github.com/repos/zeitlos/lucity/releases/latest | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p')
curl -fsSL "https://github.com/zeitlos/lucity/releases/download/v$VERSION/lucity_${VERSION}_linux_amd64.tar.gz" | tar xz
sudo install lucity /usr/local/bin/lucity

On Windows, use the Linux build inside WSL. To check that it works:

lucity version

lucity 26.9.1

Update

On macOS:

brew upgrade --cask lucity

On Linux, run the install commands again, which always fetch the latest release.

Sign in

lucity login

Your browser opens, and you sign in with GitHub just like in the dashboard. Signing in also picks an active workspace. lucity account lists the workspaces you belong to, and lucity workspace <name> switches to another one.

Ids

Commands address environments, services and databases by an id that starts with the workspace:

The project part is the project's identifier, not its display name. You can leave out the workspace, and the CLI fills in the active one, so with zeitlos-software active, vouch/development/vouch is the same service:

lucity status vouch/development/vouch

Service zeitlos-software/vouch/development/vouch: HEALTHY
Deployment zeitlos-software/vouch/development/vouch/56bc5cdfc5: ACTIVE
Replicas:   1/1 ready
Source:     7b32d9e6
Rollout:    READY

Deploy from CI

A pipeline deploys with the same lucity deploy command you use in a terminal. With --wait, the job waits until the release is live and fails when the deploy does, so the steps after it only run once the new version is up.

GitHub Actions

GitHub Actions can deploy without any secret. Turn on CI Deploys for the service under Settings → Source, and give the job the id-token: write permission:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: Install the Lucity CLI
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release download --repo zeitlos/lucity \
            --pattern 'lucity_*_linux_amd64.tar.gz' --output - | tar xz
          sudo install lucity /usr/local/bin/lucity

      - name: Deploy
        run: lucity deploy vouch/development/vouch --ref "$GITHUB_SHA" --wait

The job can then deploy the services that build from its repository and have CI Deploys turned on, and read and set their variables. For anything else, such as database commands, use an API token.

Other CI systems

Use a workspace API token. An admin creates one under Workspace settings → API tokens, with the role Member or Admin (see workspaces). The token is only shown once, so store it in your CI system's secrets as LUCITY_API_TOKEN, and the CLI picks it up from there:

lucity deploy vouch/development/vouch --ref "$CI_COMMIT_SHA" --wait

The token also determines the workspace, so there's nothing else to configure.

Reference

Every command, flag and environment variable of the CLI.

lucity <command> [arguments]

Run lucity help <command> for the details of a command.

login

Sign in through your browser.

lucity login [--api <url>]

Opens your browser to sign in with GitHub and stores the session in the config directory. Only a refresh token is written to disk, and access tokens are fetched as commands need them.

The browser hands the session back to a listener on 127.0.0.1, on port 8765, 8766 or 8767, so sign in on the machine your browser runs on. To sign in on a remote machine, forward the port with ssh -L 8765:127.0.0.1:8765 <host>, or use an API token instead.

lucity login
lucity login --api https://paas.example.com

logout

Discard the stored session.

lucity logout

Deletes the refresh token from the config directory. The platform URL and the active workspace stay, ready for the next lucity login.

account

Show who you are signed in as.

lucity account

Prints your name and email, the platform, and each workspace you belong to with your role in it, marking the active one with *. With LUCITY_API_TOKEN set, it describes the token instead.

workspace

Show or switch the active workspace.

lucity workspace
lucity workspace <workspace>

Ids that leave out the workspace, such as shop/production/web, resolve against the active workspace. LUCITY_WORKSPACE overrides it without changing the stored one.

deploy

Build and roll out a service.

lucity deploy <service> [flags]

Progress goes to stderr. Without --wait the command returns as soon as the release is queued, and prints the release id on stdout.

lucity deploy site/production/web --ref "$GITHUB_SHA" --wait
lucity deploy acme/site/production/web --ref v1.4.2 --wait --timeout 30m

Authentication

In GitHub Actions, deploys are keyless, so there is no secret to store. Grant the job permissions: id-token: write and turn on CI Deploys in the service's settings, and the CLI trades the job's OIDC token for a short-lived session that can only deploy services built from that repository. The session knows its workspace, so LUCITY_WORKSPACE is optional.

For other CI systems, set LUCITY_API_TOKEN to a workspace API token, created in the Lucity dashboard. The workspace comes from the token.

status

Show the latest rollout status of a service.

lucity status <service> [--json]

Exit status is non-zero when the active rollout is FAILED or DEGRADED, so CI can gate on it.

lucity status site/production/web
lucity status acme/site/production/web --json

vars

Manage service variables.

lucity vars list <service> [--json]
lucity vars available <env> [--json]
lucity vars set <service> KEY=VALUE... [--ref KEY=<variableID>]... [--json]

lucity vars set merges your changes into the existing variables, so variables you do not name are kept. The service then rolls out again on its current image, without a new build.

Works with a signed-in session or a workspace API token. A keyless GitHub Actions session can list and set variables too, but only for services with CI Deploys turned on that build from its own repository.

db

Manage databases.

lucity db create <env> <name> [--size <size>] [--cpu <cpu>] [--memory <mem>] [--json]
lucity db list <env> [--json]
lucity db credentials <db> [--json]
lucity db expose <db> [--json]
lucity db unexpose <db> [--json]
lucity db delete <db> [--yes] [--json]

Needs a signed-in session or a workspace API token. A keyless GitHub Actions session cannot manage databases.

token

Print a bearer token for scripting.

lucity token [--account]

Prints a short-lived access token for the active workspace, to call the API with directly.

curl https://lucity.cloud/graphql \
  -H "Authorization: Bearer $(lucity token)" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects { id } }"}'

mcp

Serve the Lucity MCP server on stdio.

lucity mcp

Speaks the Model Context Protocol on stdin and stdout, so an AI agent can create projects, deploy, provision databases and read logs with your session. MCP clients start the server themselves, so configure lucity mcp as its command rather than running it by hand.

version

Print the CLI version.

lucity version
lucity --version

Next steps

• Deployments for what happens between a commit and a running service
• Variables for service, shared and dynamic variables
• Claude plugin & MCP for letting an agent deploy for you
• API for everything the CLI doesn't cover