CLI Client
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).
cipi-cli. See cipi api for
setup instructions.
Download binary
Download the latest release for your platform from the Releases page, then:
chmod +x cipi-cli-* sudo mv cipi-cli-* /usr/local/bin/cipi-cli
Build from source
git clone https://github.com/cipi-sh/cli.git cd cli make build sudo make install
Verify installation
cipi-cli version
cipi-cli v1.6.0 (linux/amd64)
CLI Client
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:
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
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
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
CLI Client
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
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:
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).
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.
CLI Client
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
Edit flags
Logs flags
Examples
# 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.
CLI Client
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 |
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
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.
CLI Client
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.
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.
CLI Client
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+) |
cipi-cli ssl install myapp
Certificate provisioned for myapp.com
CLI Client
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 |
# 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
CLI Client
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 |
# 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
CLI Client
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 |
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
CLI Client
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 |
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.
# 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
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.
CLI Client
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) |
cipi-cli php list cipi-cli prod php install 8.5
CLI Client
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 |
cipi-cli services list cipi-cli services restart nginx cipi-cli ssh-keys add --file ~/.ssh/id_ed25519.pub cipi-cli ssh-keys list
CLI Client
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
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
CLI Client
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.
cipi-cli health set myapp --url https://myapp.com/up --expect 200 cipi-cli health check myapp cipi-cli health list
CLI Client
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 * |
--no-ensure-client-ip to set to skip that safety net.
cipi-cli ip-whitelist set 203.0.113.10 198.51.100.0/24 cipi-cli ip-whitelist show
CLI Client
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+) |
cipi-cli prod monitor cipi-cli node list --json
CLI Client
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 *.
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
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.
CLI Client
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 |
cipi-cli disk cipi-cli prod disk db cipi-cli disk --json
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.
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)
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.
CLI Client
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) |
cipi-cli jobs show 42 Job #42: deploy myapp — completed cipi-cli jobs wait 43 Waiting for job #43... completed
CLI Client
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) |
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
CLI Client
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 |
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>.
CLI Client
Global Flags
These flags are available on all commands.
# 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.
CLI Client
Requirements
The Cipi server must have the API package installed and configured
before using cipi-cli:
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) |