Installing cipi-cli

cipi-cli is a standalone Go binary that talks to the Cipi REST API from your local machine. No SSH required — manage apps, deployments, SSL, databases (including anonymized dumps), PHP versions, services, SSH keys, SMTP, healthchecks and disk usage from any terminal. Binaries are available for Linux and macOS (amd64 and arm64).

The Cipi server must have the API package installed and configured before using cipi-cli. See cipi api for setup instructions.

Download binary

Download the latest release for your platform from the Releases page, then:

bash
chmod +x cipi-cli-*
sudo mv cipi-cli-* /usr/local/bin/cipi-cli

Build from source

bash
git clone https://github.com/cipi-sh/cli.git
cd cli
make build
sudo make install

Verify installation

bash
cipi-cli version
cipi-cli v1.6.0 (linux/amd64)

Configuration

A profile is a named connection to one Cipi server (API endpoint + token). Use as many profiles as you have servers — for example prod, staging, or client-a. You need the API endpoint URL and a Sanctum token created with cipi api token create on each server.

Credentials are stored per profile in ~/.cipi/config.json with permissions 0600. Always pass a profile name — if you omit it, the CLI prompts for one instead of silently writing to default.

Interactive setup

Recommended: store the token with api token add. Equivalent helpers are configure --profile and profiles add:

bash
cipi-cli api token add prod
Cipi API endpoint: https://api.example.com
API token: 1|yourtoken...
Server profile "prod" saved → ~/.cipi/config.json

cipi-cli api token add staging
Cipi API endpoint: https://staging-api.example.com
API token: 1|stagingtoken...
Server profile "staging" saved → ~/.cipi/config.json

# Same flow via configure / profiles add
cipi-cli configure --profile prod
cipi-cli profiles add staging

Non-interactive setup

bash
cipi-cli api token add prod \
    --endpoint https://api.example.com --token "1|yourtoken..."

cipi-cli profiles add staging \
    --endpoint https://staging.example.com --token "1|yourtoken..."

Show configuration

bash
cipi-cli profiles show prod
Profile:   prod
Endpoint:  https://api.example.com
Token:     1|a8Kz...4f2a

cipi-cli profiles show
# Shows all configured server profiles

profiles

Manage multiple server connections from a single cipi-cli installation. One profile equals one server. Prefix any command with a profile name to target that server, or set a default with profiles use to omit the prefix. The aliases servers / server work the same as profiles.

Targeting a server

bash
cipi-cli prod apps list
cipi-cli staging apps show myapp
cipi-cli prod deploy myapp
cipi-cli prod ssl install myapp

With a default server set, you can run commands without the prefix:

bash
cipi-cli profiles use prod
Default profile set to "prod"

cipi-cli apps list
# Uses the prod profile

cipi-cli staging apps list
# Explicit prefix still targets staging
Command Description
cipi-cli api token add [profile] Add or update API endpoint + token for a named server profile
cipi-cli profiles List configured servers (alias: cipi-cli servers)
cipi-cli profiles add [name] [flags] Add or update a server profile (same as configure --profile)
cipi-cli profiles list List configured servers
cipi-cli profiles show [profile] Show one server profile, or all if omitted
cipi-cli profiles use <profile> Set the default server (alias: profiles default)
cipi-cli profiles delete <profile> [-y] Delete a local server profile (credentials only — nothing changes on the remote server)

api token add, profiles add, and configure accept the same flags: --endpoint and --token (plus --profile when the name is not positional).

Aliases: servers / server → profiles; profiles use → profiles default. The same management commands are also available under cipi-cli configure list, configure show, configure default, and configure delete — prefer profiles or api token add for storing credentials.

apps

Manage applications on your Cipi server.

Command Description
cipi-cli apps list List all applications
cipi-cli apps show <name> Show application details — the environment label included (cipi-cli 1.9.0+, Cipi 5.8.0+)
cipi-cli apps create [flags] Create a new application
cipi-cli apps edit <name> [flags] Edit an application
cipi-cli apps delete <name> [-y] Delete an application
cipi-cli apps suspend <name> Take an app offline (HTTP 503 maintenance page) without deleting it
cipi-cli apps unsuspend <name> Restore a suspended app to normal service
cipi-cli apps logs <name> [flags] Read paginated application logs (nginx, PHP-FPM, Laravel, worker, deploy)
cipi-cli apps fix-permissions <name> Restore the app home permissions (Cipi 5.2.1+)
cipi-cli apps artisan <name> [command...] Run an Artisan command as an async job (Cipi 5.0.3+)
cipi-cli apps run <name> [command...] Run a whitelisted app binary — see cipi-cli run-commands (Cipi 5.0.3+)
cipi-cli apps env show|set <name> Read .env, or merge keys with --set KEY=VALUE / --unset KEY (Cipi 5.0.3+)
cipi-cli apps auth show|create|update|delete <name> Manage the shared Composer auth.json (Cipi 5.0.3+)
cipi-cli apps basicauth status|enable|disable <name> HTTP Basic Auth in front of the app (--user, --password; auto-generated when omitted)
cipi-cli apps node status|restart <name> Node app status and blue-green restart (Cipi 5.4.0+)
cipi-cli apps search enable|disable <name> Meilisearch / Laravel Scout for one app (Cipi 5.2.2+)
cipi-cli apps webhook recreate <name> [--rotate-secret] Recreate the Git deploy webhook, optionally rotating CIPI_WEBHOOK_TOKEN (Cipi 5.0.6+)

Alias: app → apps. The artisan, run, env and auth subcommands need the matching token abilities (apps-artisan, apps-run, apps-env, apps-auth) and a Laravel app — custom apps have no .env or Artisan.

Create flags

--user Application name (used as Linux user and database name)
--domain Primary domain for the application
--php PHP version (e.g. 8.5)
--repository Git repository URL
--branch Git branch to deploy from
--env Environment label, e.g. production (default) or staging — lowercase letters, digits, -, _, max 32 characters (cipi-cli 1.9.0+, API 1.36+, Cipi 5.8.0+). Written to the app's .env as APP_ENV / CIPI_ENV and picks the cipi-<env>.yml the app reads before cipi.yml
--custom Create a custom (non-Laravel) app with htdocs deploy
--docroot Document root relative to htdocs (custom apps only)
--engine Database engine: mariadb or pgsql (Cipi 4.8+)
--octane Laravel Octane mode: true, false or frankenphp (Cipi 5.0+)
--node Create a Node app: spa, static or ssr (Cipi 5.4.0+). A repository is required and --php is not accepted
--framework Node framework preset: next, nuxt, sveltekit, astro, remix or vite
--node-version Node major version (e.g. 22 or 24)
--build Node build command
--start Node start command (SSR apps)
--output Node build output directory (spa / static apps)
--health-path Node health path checked during blue-green restarts (SSR apps)

Edit flags

--php Change PHP version
--repository Update Git repository URL
--branch Change deploy branch
--env Change the environment label (cipi-cli 1.9.0+, Cipi 5.8.0+); same as cipi app edit --env
--domain Rename the primary domain (requires Cipi 4.6.2+ and API 1.9.0+)
--node … --node, --node-version, --build, --start, --output, --health-path — update the Node app settings listed under create flags

Logs flags

--type Log type filter: all (default), nginx, php, worker, deploy, or laravel
--page Page number, starting at 1 for the most recent lines (default 1)
--per-page Lines per log file per page (default 50, max 1000; requires API 1.11.9+)

Examples

bash
# List all apps
cipi-cli apps list

# Create a Laravel app
cipi-cli apps create --user=myapp --domain=myapp.com \
    --php=8.5 --repository=git@github.com:acme/myapp.git --branch=main \
    --node-build='npm ci && npm run build'   # asset build on every deploy (1.7.0+)

# A staging app of the same repository (cipi-cli 1.9.0+, Cipi 5.8.0+): reads cipi-staging.yml before cipi.yml
cipi-cli apps create --user=myapp-stg --domain=staging.myapp.com \
    --repository=git@github.com:acme/myapp.git --branch=develop --env=staging

# Create a custom (non-Laravel) app
cipi-cli apps create --user=landing --domain=landing.acme.com \
    --custom --docroot=dist

# Edit an existing app
cipi-cli apps edit myapp --php=8.4

# Suspend staging for maintenance
cipi-cli apps suspend staging

# Read recent deploy logs (page 1 = newest lines)
cipi-cli apps logs myapp --type=deploy

# Paginate older nginx lines
cipi-cli apps logs myapp --type=nginx --page=2 --per-page=100

# Run Artisan, read and update .env
cipi-cli apps artisan myapp migrate --force
cipi-cli apps env show myapp
cipi-cli apps env set myapp --set APP_DEBUG=false --unset OLD_KEY

# Create a Node SSR app
cipi-cli apps create --user=web --domain=web.acme.com --node=ssr --framework=next \
    --repository=git@github.com:acme/web.git --branch=main

# Recreate the Git webhook with a new secret
cipi-cli apps webhook recreate myapp --rotate-secret

# Delete an app (skip confirmation)
cipi-cli apps delete myapp -y

Since 1.7.0 (Cipi 5.6.0, API 1.34+), apps create prints the app's credentials, deploy key and build when the job finishes, and both apps create and apps edit (new repository or branch) report whether the deploy key can read the repository. When it cannot, the output names git's error and the command to run on the server — for example cipi git github-token <token> && cipi git refresh myapp. Interactive apps create also asks for the build command of a Laravel app; Enter skips it. --json returns the job result, repository_access included.


domains

List every primary domain and alias across all apps on the server in a single table — the remote counterpart to cipi domains on the server. Useful for auditing DNS coverage or spotting domains missing SSL before a certificate renewal.

Command Description
cipi-cli domains List every domain and alias across all apps
bash
cipi-cli domains
  DOMAIN              APP     KIND    TYPE     PHP   SSL
  api.myapp.com       myapp   alias   Laravel  8.5   ✓
  myapp.com           myapp   primary Laravel  8.5   ✓
  www.myapp.com       myapp   alias   Laravel  8.5   ✓

3 domains · 1 app · 3 certificates
The global domain map is built from GET /api/apps on the server. It requires Cipi 4.5.5+ on the server (for the underlying cipi domains data) but no minimum API package version.

deploy

Trigger deployments, rollback to the previous release, or unlock a stuck deployment.

Command Description
cipi-cli deploy <app> Trigger a zero-downtime deployment
cipi-cli deploy rollback <app> [-y] Rollback to previous release
cipi-cli deploy unlock <app> Unlock a stuck deployment
cipi-cli deploy config show|set <app> Read or update structured deploy.php options (Cipi 5.0.3+)
cipi-cli deploy audit <app> [--days N] Deploy audit ledger: origin, operator, IP and commit of every deploy (Cipi 5.4.0+)
cipi-cli yml <app> The app's cipi.yml: file, validity, auto-apply and what applying would change (Cipi 5.6.4+); the environment and the cipi-<env>.yml in use (cipi-cli 1.9.0+, Cipi 5.8.0+)
cipi-cli yml apply <app> Apply the committed cipi.yml as an async job (Cipi 5.6.4+)
cipi-cli yml auto <app> on|off|status Apply cipi.yml after every successful deploy, or stop (Cipi 5.6.4+)

deploy config set flags: --keep-releases N, --migrate, --optimize, --storage-link, --queue-restart, --horizon-terminate, --predeploy-snapshot, --node-build CMD and --extra-artisan CMD (repeatable). The remote counterparts of cipi deploy-config and the deploy audit ledger.

The yml commands are the remote side of cipi yml plan | apply | auto. They need API 1.35+, Cipi 5.6.4+ and a token with yml-view (read) and yml-manage (apply, auto). A token created before 1.35 has neither, so expect a 403 until you issue a new one. Turning auto-apply on asks for confirmation: from then on, anyone who can push to the repository can change the app's server settings.

bash
cipi-cli deploy myapp
Deploying myapp...
Polling job #42... completed
Deployed to release #14. Zero downtime.

cipi-cli deploy rollback myapp
Rolled back to release #13.

ssl

Install Let's Encrypt certificates for your applications.

Command Description
cipi-cli ssl install <app> Install Let's Encrypt certificate (covers primary domain and all aliases)
cipi-cli ssl force <app> Re-apply the HTTP → HTTPS redirect (Cipi 4.8+)
bash
cipi-cli ssl install myapp
Certificate provisioned for myapp.com

www

Manage the www ↔ apex counterpart of an app — the remote side of cipi www. DNS for the domain (and its aliases) must already point to the server. Requires Cipi 4.8+ (API 1.12+) and the www-manage ability.

Command Description
cipi-cli www status <app> Show the www / apex redirect status
cipi-cli www add <app> Add the www or apex counterpart as an alias
cipi-cli www force-to-root <app> 301 redirect www → apex
cipi-cli www force-from-root <app> 301 redirect apex → www
cipi-cli www clear <app> Remove the canonical www redirect
bash
# Add www.myapp.com and make it canonical
cipi-cli www add myapp
cipi-cli www force-from-root myapp
cipi-cli www status myapp

redirect / proxies

Whole-app and path redirects, plus prefix reverse proxies — the remote side of cipi redirect and cipi proxy. Requires Cipi 5.4.1+ (API sudoers, API 1.31+) and the redirects-view|manage / proxies-view|manage abilities. Aliases: redirects → redirect, proxy → proxies.

Command Description
cipi-cli redirect list <app> List the whole-app redirect and every path redirect
cipi-cli redirect set <app> --to URL [--code 301] [--keep-path] Redirect the whole app to a URL (one hop; path and query kept unless --keep-path=false)
cipi-cli redirect enable|disable <app> Toggle the whole-app redirect without removing it
cipi-cli redirect unset <app> Remove the whole-app redirect
cipi-cli redirect add <app> --from /path --to URL [--code] [--keep-path] Add a path redirect — a trailing slash on --from means prefix match
cipi-cli redirect remove <app> --from /path Remove a path redirect
cipi-cli proxies list <app> List prefix reverse proxies
cipi-cli proxies add <app> --prefix /api --upstream URL [flags] Proxy a path prefix to an upstream (--strip-prefix, --preserve-host, --timeout 60, --buffering)
cipi-cli proxies remove <app> --prefix /api Remove a prefix proxy
bash
# Send the old blog to the new one, keep paths
cipi-cli redirect add myapp --from /blog/ --to https://blog.acme.com/

# Proxy /api to an internal service
cipi-cli proxies add myapp --prefix /api --upstream http://127.0.0.1:8080 --strip-prefix
cipi-cli proxies list myapp

aliases

Manage domain aliases for an application.

Command Description
cipi-cli aliases list <app> List all aliases for an app
cipi-cli aliases add <app> <domain> Add a domain alias
cipi-cli aliases remove <app> <domain> [-y] Remove a domain alias
bash
cipi-cli aliases add myapp www.myapp.com
Alias www.myapp.com added to myapp.

cipi-cli aliases list myapp
  www.myapp.com
  api.myapp.com

# Re-run ssl install to include new aliases in the certificate
cipi-cli ssl install myapp

db

Manage MariaDB and PostgreSQL databases on the server, and request anonymized dumps from Laravel apps that run cipi/agent. Aliases: database, dbs → db.

Command Description
cipi-cli db engines List installed database engines and the server default (Cipi 4.8+)
cipi-cli db install <engine> Install an engine: mariadb or pgsql (Cipi 5.0.6+)
cipi-cli db list [--engine E] List databases with their size, optionally filtered by engine
cipi-cli db create <name> [--engine E] Create a database (MariaDB unless --engine pgsql)
cipi-cli db delete <name> [-y] Delete a database — API < 1.19 only; newer servers use cipi db delete on the host
cipi-cli db backup <name> Create a compressed backup on the server
cipi-cli db restore <name> [-y] Restore the latest backup (overwrites current data)
cipi-cli db password <name> [-y] Regenerate the password and update the linked app .env
cipi-cli db anonymize <app> --email <addr> Request an anonymized dump of the app database via cipi/agent (cipi-cli 1.5.0+)
cipi-cli db anonymize download <url> [-o file] Download the dump from the signed link received by email
bash
cipi-cli db list
  NAME       SIZE
  myapp      24.5 MB
  blog       8.2 MB

cipi-cli db backup myapp
Backup created: myapp_20260402_143022.sql.gz

cipi-cli db restore myapp -y
Database restored successfully.

Anonymized dumps (cipi/agent)

The anonymizer is not part of the Cipi API: it lives in the cipi/agent package inside the Laravel app. The CLI reads the app URL (APP_URL, else https://<primary domain>) and CIPI_ANONYMIZER_TOKEN from the app .env through the API (apps-view + apps-env abilities), then calls POST /<CIPI_ROUTE_PREFIX>/db on the app itself. The agent runs the job in the app queue and emails a signed download link valid for 15 minutes.

bash
# One-time setup on the app (all through the Cipi API)
cipi-cli apps artisan myapp cipi:service anonymize --enable
cipi-cli apps artisan myapp cipi:generate-token anonymize
cipi-cli apps artisan myapp cipi:init-anonymize
# then edit /home/myapp/.db/anonymization.json on the server

# Request a dump — the signed link arrives by email
cipi-cli prod db anonymize myapp --email dev@example.com
✓ Anonymization job queued for 'myapp'

# Download it: default name from the server, -o - streams to stdout
cipi-cli db anonymize download "https://myapp.com/cipi/db/<token>?expires=…&signature=…" -o myapp.sql
cipi-cli db anonymize download "<signed url>" -o - | mysql -u root myapp_local
--email, -e Address that receives the signed download link (prompted when omitted)
--url Override the app base URL, e.g. when the app redirects to www — redirects are never followed
--token Override the bearer token read from .env
--output, -o download: output file (- for stdout)
--force, -f download: overwrite an existing file
Requires cipi-cli 1.5.0+, Cipi 5.0.3+ / API 1.14+ (for apps env) and cipi/agent 1.1.1+ with the anonymizer enabled in the app. Custom and Node apps are refused. Every failure names the fix — anonymizer disabled, missing token, missing anonymization.json, invalid token, or an app that redirects (pass --url). Links expire after 15 minutes; request a new dump when they do.

php

Installed PHP versions and PHP-FPM status — the remote side of cipi php. Requires Cipi 5.0.6+ (API 1.15+) and the php-view / php-manage abilities. Switching the default version and removing versions stay host-only (cipi php switch|remove).

Command Description
cipi-cli php list Installed versions, FPM status and the server default
cipi-cli php install <version> Install PHP 8.3, 8.4 or 8.5 (async job)
bash
cipi-cli php list
cipi-cli prod php install 8.5

services / ssh-keys

System services and the authorized SSH keys of the cipi user — the remote side of cipi service and cipi ssh. Requires Cipi 5.0.6+ (API 1.15+) with services-view|manage and ssh-view|manage. Aliases: service → services, ssh → ssh-keys.

Command Description
cipi-cli services list [name] System services and their status, or one service
cipi-cli services restart <name> Restart a service (nginx, mariadb, php8.5-fpm, …)
cipi-cli ssh-keys list Authorized keys of the cipi user, with ids
cipi-cli ssh-keys add [key] [--file F] Add a public key, inline or from a .pub file
cipi-cli ssh-keys remove <id> [-y] Remove a key by id
bash
cipi-cli services list
cipi-cli services restart nginx

cipi-cli ssh-keys add --file ~/.ssh/id_ed25519.pub
cipi-cli ssh-keys list

smtp

Configure the outgoing email the server uses for notifications — the remote side of email notifications. The stored password is never shown. Requires Cipi 5.0.7+ (API 1.15+) and smtp-view|manage.

Command Description
cipi-cli smtp show Current SMTP configuration
cipi-cli smtp set [flags] Create or update the configuration; omitted flags keep the stored values
cipi-cli smtp test Send a test email
cipi-cli smtp enable|disable Toggle notifications
cipi-cli smtp delete [-y] Remove the configuration

Set flags

--host SMTP host
--port SMTP port (default 587)
--user SMTP username
--password SMTP password — required the first time; omit to keep the stored one
--from Sender address
--to Notification recipient
--tls Use STARTTLS / TLS (default on)
--enabled Enable notifications after saving (default on)
--no-test Do not send a test email after saving
bash
cipi-cli smtp set --host smtp.example.com --port 587 --user notify@example.com \
    --password "s3cret" --from notify@example.com --to ops@example.com
cipi-cli smtp test

health

HTTP healthchecks per app — the remote side of cipi health. Requires Cipi 5.0.7+ (API 1.15+) and health-view|manage.

Command Description
cipi-cli health list All configured app healthchecks and their state
cipi-cli health show <app> One app's healthcheck and last result
cipi-cli health set <app> [--url] [--expect] Enable or update the check
cipi-cli health unset <app> Disable the check
cipi-cli health check <app> Run the check now; exits 1 when unhealthy

Without --url, https://<primary domain>/up is checked (wildcard-domain apps need an explicit URL). --expect is the HTTP status considered healthy (default 200). The exit code of health check makes it usable as a CI gate.

bash
cipi-cli health set myapp --url https://myapp.com/up --expect 200
cipi-cli health check myapp
cipi-cli health list

ip-whitelist

Restrict which client IPs may call the panel API (default * = allow all). Requires Cipi 5.0.8+ (API 1.15+) and ip-whitelist-view|manage.

Command Description
cipi-cli ip-whitelist show Show the API client IP allowlist
cipi-cli ip-whitelist set <entries...> Replace the whitelist (* = allow all)
cipi-cli ip-whitelist add|remove <ip> Add or remove one IP / CIDR
cipi-cli ip-whitelist allow-all Reset to *
When restricting, the IP you are calling from is kept in the list so you do not lock yourself out. Pass --no-ensure-client-ip to set to skip that safety net.
bash
cipi-cli ip-whitelist set 203.0.113.10 198.51.100.0/24
cipi-cli ip-whitelist show

Server insights

Read-only views of host features, each mirroring its cipi counterpart on the server and needing the matching *-view ability. All support --json.

Command Description
cipi-cli search status Meilisearch status (Cipi 5.2.2+)
cipi-cli node list Installed Node runtimes (Cipi 5.4.0+)
cipi-cli monitor System monitor checks and state (Cipi 5.3.0+)
cipi-cli packages Optional host packages catalog (Cipi 5.2.2+)
cipi-cli zt Cloudflare Zero Trust status (Cipi 5.3.0+)
cipi-cli run-commands Whitelisted binaries accepted by apps run (Cipi 5.0.3+)
bash
cipi-cli prod monitor
cipi-cli node list --json

status

Read the same host snapshot as cipi status on the server — via GET /api/status. Bare status shows a global overview (one row per configured server). Pass a profile name (or use a profile prefix) for full details.

Command Description
cipi-cli status Global overview — one row per server (alias: status all)
cipi-cli status <profile> Full details for one server
cipi-cli <profile> status Same detail view, via profile prefix

Global columns: NAME, IP, CPU, RAM, HDD, APPS, SVC, CIPI. The default profile is marked with *.

bash
cipi-cli status
  NAME      IP             CPU   RAM           HDD          APPS  SVC     CIPI
  prod*     203.0.113.10   12%   48% (3840M)   42G/80G 53%  3     8/8 ok  4.6.3
  staging   203.0.113.20   4%    31% (2048M)   18G/40G 45%  1     8/8 ok  4.6.3

  * default profile
  Detail: cipi-cli status <name>

cipi-cli status prod
Server status — prod
  Endpoint   https://api.example.com
  Hostname   prod-01
  IP         203.0.113.10
  OS         Ubuntu 24.04
  Uptime     12 days
  Cipi       4.6.3
  CPU        12%
  RAM        3840/8192 MB (48%)
  HDD        42G/80G (53%)
  Apps       3
Requires the API token ability status-view and GET /api/status on the server (API 1.11.6+). Create or rotate the token with cipi api token create and include status-view.

disk

Who is filling the disk — the same figures as cipi disk on the host, read from GET /api/disk and GET /api/disk/dbs. An app is its home (releases, shared storage, logs) plus its database, largest first. The server measures sizes when asked, so the CLI waits up to three minutes. Requires cipi-cli 1.6.0+, Cipi 5.5.2+ (API sudoers; the host command exists since 5.5.0), API 1.33+ and the disk-view ability.

Command Description
cipi-cli disk The filesystem /home is on, then every app (GB and %)
cipi-cli disk db Every database per engine, in MB (aliases: dbs, databases)
cipi-cli disk --json The same figures for scripts (disk db --json too)
cipi-cli <profile> disk Same reading, on one server
bash
cipi-cli disk
cipi-cli prod disk db
cipi-cli disk --json
output
  Server disk
  MOUNT                          SIZE         USED         FREE     USE
  /                         100.00 GB     40.00 GB     60.00 GB     40%

  Apps (3) — % of the 100.00 GB on /
  APP                           FILES     DATABASE        TOTAL    DISK  LIMIT
  shop                        2.00 GB      1.00 GB      3.00 GB    3.0%  10 GB (30%)
  blog                        0.50 GB     120.4 MB      0.62 GB    0.6%  —
  front                       0.10 GB      0.00 GB      0.10 GB    0.1%  —
  All apps                                              3.72 GB    3.7%
  Everything else                                      36.28 GB   36.3%

FILES is the app home. DATABASE is the database named after the app and, when shared/.env points DB_DATABASE at another one, that one too. TOTAL is both; DISK is that total as a percentage of the filesystem. LIMIT is the soft limit set on the host with cipi app limits <app> --disk=<GB> — alerts only, nothing is blocked — and reads over once passed, — when the app has none. Everything else is the rest of the used space: system, packages, logs, local backups, databases that belong to no app. Sizes below 0.01 GB are printed in MB. --json carries files_kb, database_kb and total_kb next to the rounded GB, plus limit_gb, limit_percent and over_limit.

disk db — every database, in MB

MariaDB and PostgreSQL report one size per database. Valkey only knows how many keys each logical database holds, and Meilisearch how many documents each index has: for those two the size is the engine's, in memory and on disk. An engine that is not installed is left out. How each engine is measured is on the host command.

output
  MariaDB — sizes in MB
  DATABASE                                               SIZE
  blog                                                 2.0 MB
  shop                                               200.0 MB
  On disk                                          500.0 MB (whole engine)

  Valkey — sizes in MB
  DATABASE                                     KEYS      SIZE
  db0                                          1204         —
  Memory in use                                    12.3 MB
  On disk                                        3.0 MB (whole engine)
Requires the API token ability disk-view. A token created before API 1.33 does not have it — run cipi api token create on the host and include disk-view. HTTP 503, or terminal is required, means the server is older than Cipi 5.5.2: cipi self-update so the API sudoers allow cipi disk.

jobs

Write operations (create, edit, delete, deploy, SSL, etc.) are asynchronous on the Cipi API. The CLI automatically polls for job completion and displays a spinner while waiting. If you prefer to handle polling manually, use the jobs commands.

Command Description
cipi-cli jobs show <id> Show job status
cipi-cli jobs wait <id> Wait for a job to complete (blocking)
bash
cipi-cli jobs show 42
Job #42: deploy myapp — completed

cipi-cli jobs wait 43
Waiting for job #43... completed

update

Update cipi-cli to the newest release from GitHub. The command picks the highest semver among published releases (not GitHub’s “latest” flag, which can point at an older tag), downloads the matching binary for your platform, verifies its SHA-256 checksum, and replaces the running binary in place. Aliases: self-update, upgrade.

Command Description
cipi-cli update Update to the highest published semver
cipi-cli update --force Reinstall even if already up to date (allows downgrade)
bash
cipi-cli update
Downloading cipi-cli v1.6.0...
Checksum verified. Updated to v1.6.0.

# Aliases work the same
cipi-cli self-update
cipi-cli upgrade

# If installed in a system path, use sudo
sudo cipi-cli update

completion

Install shell autocompletion for cipi-cli. The recommended path is completion install, which detects your shell, writes the completion script, and hooks it into your rc file (idempotent).

Command Description
cipi-cli completion install Auto-detect shell and install completion
cipi-cli completion install --shell zsh Install for a specific shell (zsh, bash, or fish)
cipi-cli completion zsh Print the zsh completion script to stdout
cipi-cli completion bash Print the bash completion script to stdout
cipi-cli completion fish Print the fish completion script to stdout
bash
cipi-cli completion install
Installing zsh completion...
Completion installed → ~/.cipi/completions/cipi-cli.zsh
Hooked into ~/.zshrc

# Or pin a shell explicitly
cipi-cli completion install --shell bash

For zsh and bash, the script is written under ~/.cipi/completions/ and a source line is appended to your shell rc file. For fish, the script goes to ~/.config/fish/completions/ (auto-loaded). Reload the shell afterwards, then try cipi-cli <TAB>.


Global Flags

These flags are available on all commands.

--json Output in JSON format — useful for scripting and CI/CD pipelines
--no-color Disable colored output
--help Show help for any command
bash
# JSON output for scripting
cipi-cli apps list --json
[{"name":"myapp","domain":"myapp.com","php":"8.5"}, ...]

# Pipe to jq for filtering
cipi-cli apps list --json | jq '.[].name'
"myapp"
"blog"

# Help for a specific command
cipi-cli apps create --help

Releases

Releases are automated via GitHub Actions. Pre-built binaries for Linux (amd64/arm64) and macOS (amd64/arm64) are published with SHA-256 checksums on the GitHub Releases page.

Source code

cipi-cli is open source, MIT licensed, and written in Go. Contributions welcome on GitHub.


Requirements

The Cipi server must have the API package installed and configured before using cipi-cli:

bash
cipi api <domain>
cipi api ssl
cipi api token create

New app PHP versions must be 8.3, 8.4, or 8.5 (Cipi 4.5.4+). Some CLI features depend on specific server and API versions:

Feature Minimum Cipi Minimum API
Suspend / unsuspend (apps suspend) 4.5.8 1.8.1
Rename primary domain (apps edit --domain) 4.6.2 1.9.0
App logs (apps logs) — 1.11.9
Server status (status) — GET /api/status + status-view (1.11.6+)
Global domain map (domains) 4.5.5 — (built from /api/apps)
Multi-engine DB (db engines, --engine) 4.8 1.12+
www / ssl force 4.8 1.12+
apps env / auth / artisan / run / deploy config 5.0.3 1.14+
php / ssh-keys / services / db install / apps webhook recreate 5.0.6 1.15+
smtp / health 5.0.7 1.15+
ip-whitelist 5.0.8 1.15+
apps fix-permissions 5.2.1 1.31+
apps search / search status / packages 5.2.2 1.31+
monitor / zt 5.3.0 1.31+
redirect / proxies (API sudoers) 5.4.1 1.31+
Node apps / deploy audit 5.4.0 1.31+
Disk usage (disk, disk db, cipi-cli 1.6.0+) 5.5.2 (API sudoers) 1.33+ and disk-view
apps create --node-build, repository check on create/edit (cipi-cli 1.7.0+) 5.6.0 1.34+
yml (plan, apply, auto-apply) 5.6.4 (API sudoers) 1.35+ and yml-view / yml-manage
apps create|edit --env, environment in apps show and yml (cipi-cli 1.9.0+) 5.8.0 1.36+
Anonymized dumps (db anonymize, cipi-cli 1.5.0+) 5.0.3 1.14+ (plus cipi/agent 1.1.1+ in the app)