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
Install it with Homebrew(opens in a new tab):
brew install --cask zeitlos/tap/lucity
Download the latest release and put the binary on your PATH:
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 an ARM machine, use arm64 in place of amd64.
On Windows, use the Linux build inside WSL. To check that it works:
lucity version
lucity 26.9.1
Update
The CLI keeps itself up to date. Once a day it asks GitHub for the latest release, and when a newer one is out, it downloads it in the background, checks it against the release signature and swaps it in. Your next command runs the new version and says so. The MCP server does the same, so your agent gets the new version in its next session.
To update right away:
lucity update
The CLI can't replace itself in a directory only root can write to, like /usr/local/bin from the Linux install above. There it tells you about new releases instead, and sudo lucity update installs them. Put the binary in a directory you own, like ~/.local/bin, and it updates on its own.
Set LUCITY_NO_AUTO_UPDATE=1 to only be told about new releases, for example when you run your own Lucity platform and upgrade it on your own schedule. LUCITY_NO_UPDATE_CHECK=1 stops looking for releases altogether.
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
vouch with a vouch service and a feedback database in its development environment.Commands address environments, services and databases by an id that starts with the workspace:
| Resource | Id | Example |
|---|---|---|
| Environment | workspace/project/environment | zeitlos-software/vouch/development |
| Service | workspace/project/environment/service | zeitlos-software/vouch/development/vouch |
| Database | workspace/project/environment/database | zeitlos-software/vouch/development/feedback |
Every part is an id, not a name. Names are what the dashboard shows, and they can contain spaces and change at any time, while an id stays the same for good. You find a resource's id in its settings in the dashboard. 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 API tokens in the menu on the left of the project list, 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]
| Command | Description |
|---|---|
login [--api <url>] | Sign in through your browser |
logout | Discard the stored session |
account | Show who you are signed in as, and your workspaces |
workspace [<workspace>] | Show or switch the active workspace |
deploy <service> | Build and roll out a service |
status <service> | Show the latest rollout status of a service |
restart <service> | Replace the instances of a service with fresh ones |
vars <command> | Manage service variables (list, available, set) |
db <command> | Manage databases (create, list, credentials, expose, unexpose, delete) |
token [--account] | Print a bearer token for scripting |
mcp | Serve the Lucity MCP server on stdio |
claude plugin | Write the plugin for Claude Code and print its path |
update | Update the CLI to the latest release |
version | Print the CLI version |
Run lucity help <command> for the details of a command.
| Variable | Description |
|---|---|
LUCITY_API_URL | Platform URL, in place of the one you signed in to |
LUCITY_WORKSPACE | Workspace to use, in place of the active one |
LUCITY_API_TOKEN | Workspace API token, used in place of the stored session |
LUCITY_CONFIG_DIR | Directory holding the session (default: $XDG_CONFIG_HOME/lucity or ~/.config/lucity) |
LUCITY_NO_AUTO_UPDATE | Set to 1 to only be told about new releases, not install them |
LUCITY_NO_UPDATE_CHECK | Set to 1 to stop looking for new releases, and updating to them |
login
Sign in through your browser.
lucity login [--api <url>]
| Flag | Description |
|---|---|
--api <url> | Platform to sign in to. Defaults to LUCITY_API_URL, then the platform you last signed in to, then https://lucity.cloud(opens in a new tab). |
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>
| Argument | Description |
|---|---|
<workspace> | Workspace to switch to. lucity account lists the ones you belong to. |
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]
| Argument | Description |
|---|---|
<service> | Full service id (workspace/project/environment/service), or the project/environment/service form relative to the active workspace. |
| Flag | Description |
|---|---|
--ref <ref> | Branch, tag, or commit to build (default: the service's branch) |
--no-cache | Build every step from scratch, e.g. for a site that fetches content at build time |
--wait | Block until the release is live or failed, and exit non-zero on failure |
--timeout <dur> | Give up waiting after this long (default 20m, only with --wait) |
--interval <dur> | Poll interval while waiting (default 4s) |
--json | Emit the final release as JSON on stdout |
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]
| Argument | Description |
|---|---|
<service> | Full service id (workspace/project/environment/service), or the project/environment/service form relative to the active workspace. |
| Flag | Description |
|---|---|
--json | Emit the service, its active deployment and its latest release as JSON on stdout |
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
restart
Replace the instances of a service with fresh ones.
lucity restart <service>
| Argument | Description |
|---|---|
<service> | Full service id (workspace/project/environment/service), or the project/environment/service form relative to the active workspace. |
The service keeps the image and settings it already runs; nothing is built. Follow the rollout with lucity status <service>.
lucity restart site/production/web
vars
Manage service variables.
lucity vars list <service> [--json]
lucity vars available <env> [--json]
lucity vars set <service> KEY=VALUE... [--from-file KEY=<path>]... [--ref KEY=<variableID>]... [--json]
| Command | Description |
|---|---|
list | Show the variables set on a service |
available | Show the variables a service in the environment can link to, from its databases, key-value stores, buckets and shared variables |
set | Add or change variables on a service |
| Argument | Description |
|---|---|
<service> | Service id (workspace/project/environment/service) or its relative form. |
<env> | Environment id (workspace/project/environment) or its relative form. |
| Flag | Description |
|---|---|
--from-file KEY=<path> | Set KEY to the contents of a file, line breaks included, such as a PEM key or certificate. Use - as the path to read stdin |
--ref KEY=<variableID> | Bind KEY to an available variable (list them with lucity vars available) |
--json | Emit the result as JSON on stdout |
lucity vars set shop/production/web --from-file JWT_PRIVATE_KEY=./jwt.pem
op read op://vault/web/key | lucity vars set shop/production/web --from-file SIGNING_KEY=-
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> [--id <id>] [--size <size>] [--cpu <cpu>] [--memory <mem>] [--json]
lucity db list <env> [--json]
lucity db credentials <db> [--json]
lucity db query <db> [<sql>] [--file <path>] [--json]
lucity db expose <db> [--json]
lucity db unexpose <db> [--json]
lucity db delete <db> [--yes] [--json]
| Command | Description |
|---|---|
create | Create a PostgreSQL database in an environment |
list | List the databases in an environment |
credentials | Print the connection details, password included |
query | Run one SQL statement and print its rows, at most 1,000 |
expose | Give the database a public hostname, reachable over TLS from this machine's address only |
unexpose | Remove the public hostname and its allowed addresses again |
delete | Delete the database and all of its data |
| Argument | Description |
|---|---|
<env> | Environment id (workspace/project/environment) or its relative form. |
<name> | What people read, any text. Quote it when it has spaces. |
<db> | Database id (workspace/project/environment/database) or its relative form. |
| Flag | Description |
|---|---|
--id <id> | Id for a new database, 2-16 lowercase letters, digits and hyphens. Derived from <name> when left out. |
--size <size> | Storage size for a new database (e.g. 32Gi) |
--cpu <cpu> | CPU limit for a new database, e.g. 500m (with --memory) |
--memory <mem> | Memory limit for a new database, e.g. 512Mi (with --cpu) |
--file <path> | Read the SQL for query from a file, or from stdin with - |
--yes | Skip the confirmation prompt on delete |
--json | Emit the result as JSON on stdout |
lucity db query runs the statement as the database's own user and commits it right away. Values come back as text, NULL as null in --json. For more than 1,000 rows, page with LIMIT and OFFSET, or expose the database and use pg_dump.
lucity db query shop/production/main "select id, email from users limit 10"
lucity db query shop/production/main --file report.sql --json | jq '.rows'
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]
| Flag | Description |
|---|---|
--account | Print the account token instead. API calls that read from GitHub on your behalf send it in the X-Lucity-Account-Token header. |
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.
claude
Set up Claude Code.
lucity claude plugin
| Command | Description |
|---|---|
plugin | Write the Lucity plugin for Claude Code to a local directory and print its path |
The Lucity plugin marketplace runs lucity claude plugin to install the plugin, so the deploy skill always comes from the same version as the MCP server. Update the CLI, and Claude Code picks up the matching plugin in its next session.
The plugin lands in the lucity/claude-plugin directory of your user cache directory, and older versions there are removed.
update
Update the CLI to the latest release.
lucity update
Downloads the latest release from GitHub, checks it against the release signature, and replaces this binary with it.
The CLI also does this on its own: once a day it looks for a newer release, and updates itself in the background while you keep working. Set LUCITY_NO_AUTO_UPDATE to only be told about new releases instead.
When the binary sits in a directory only root can write to, such as /usr/local/bin, it can't update itself. Run sudo lucity update there.
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