Command-line interface for Cipi — manage servers, apps, databases, SSL certificates, deployments, PHP, services, SMTP, healthchecks, disk usage, and an app's cipi.yml from the terminal.
git clone https://github.com/cipi-sh/cli.git
cd cli
make build
sudo make installDownload the latest release for your platform from the Releases page, then:
chmod +x cipi-cli-*
sudo mv cipi-cli-* /usr/local/bin/cipi-cliA profile is a named connection to a Cipi server (API endpoint + token).
Use as many profiles as you have servers. The alias servers works like profiles.
cipi-cli prod apps list # explicit profile
cipi-cli apps list # uses the default profileCreate a token on the Cipi host first (cipi api token create), then store it locally under a profile name:
cipi-cli api token add prod
cipi-cli api token add staging
# or: cipi-cli configure --profile prod
# or: cipi-cli profiles add stagingYou will be prompted for:
- Profile name — alias for this server (e.g.
prod,staging) if you omit it - API endpoint — the URL of your Cipi API (e.g.
https://api.example.com) - Token — the Sanctum token from the server
Credentials are stored per profile in ~/.cipi/config.json (permissions 0600).
Omitting the profile name does not write silently to default — you will be asked.
Non-interactive:
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..."cipi-cli profiles # list servers (alias: cipi-cli servers)
cipi-cli profiles show prod # inspect one server
cipi-cli profiles use prod # set default server
cipi-cli profiles delete staging # remove a local server profile (-y to skip confirm)Deleting a profile only removes local credentials — nothing changes on the remote server.
Prefix any command with the profile name to target that server:
cipi-cli prod apps list
cipi-cli staging apps show myapp
cipi-cli prod deploy myapp
cipi-cli prod ssl install myapp
cipi-cli status # overview of all profiles
cipi-cli status prod # details for one serverAfter cipi-cli profiles use prod, you can omit the prefix:
cipi-cli apps list # uses the default profile (prod)Every command has detailed help:
cipi-cli --help
cipi-cli profiles --help
cipi-cli apps --help
cipi-cli deploy --helpcipi-cli apps list List all applications
cipi-cli apps show <name> Show application details
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> Suspend an application (HTTP 503)
cipi-cli apps unsuspend <name> Bring a suspended application back online
cipi-cli apps logs <name> [flags] Read application logs
cipi-cli apps fix-permissions <name> Restore app home permissions (Cipi 5.2.1+)
cipi-cli apps artisan <name> [command...] Run Artisan (async job, Cipi 5.0.3+)
cipi-cli apps run <name> [command...] Run whitelisted command (Cipi 5.0.3+)
cipi-cli apps env show|set <name> Read/update .env keys (Cipi 5.0.3+)
cipi-cli apps auth show|create|update|delete Manage shared auth.json (Cipi 5.0.3+)
cipi-cli apps basicauth status|enable|disable HTTP Basic Auth
cipi-cli apps node status|restart <name> Node app status / blue-green restart (5.4.0+)
cipi-cli apps search enable|disable <name> Meilisearch/Scout per app (5.2.2+)
cipi-cli apps webhook recreate <name> Recreate Git webhook [--rotate-secret] (5.0.6+)
Alias: app → apps.
Create flags: --user, --domain, --php, --repository, --branch, --custom, --docroot, --engine, --octane, --node, --framework, --node-version, --build, --start, --output, --health-path (Node apps take no --php), --node-build (Laravel apps only: the asset build run inside every deploy before go-live, e.g. --node-build "npm ci && npm run build"; must start with npm/npx/yarn/pnpm/bun/node, && and ; allowed, no pipes/redirects/backticks/$( ), max 200 chars; requires Cipi 5.6.0+ / API 1.34+). The interactive flow offers an optional build command prompt for Laravel apps.
When the create job completes the CLI prints the app credentials (SSH, database), deploy key, webhook and build. With Cipi 5.6.0+ / API 1.34+, apps create and apps edit --repository/--branch also report whether the deploy key can read the repository: reachable (with the branch), reachable but the branch is missing, or not readable (the first deploy will fail; git's error and the fix command to run on the server are shown). Older servers report nothing. With --json, the job result is printed as {"data": …}, repository_access and build included.
Edit flags: --php, --repository, --branch, --domain (rename primary domain; requires Cipi 4.6.2+ / API 1.9.0+), plus Node flags above
Logs flags: --type (default all: nginx, php, worker, deploy, laravel), --page (default 1 = most recent), --per-page (default 50, max 1000; requires API 1.11.9+)
cipi-cli domains List every domain and alias across all apps
Alias: domain → domains.
For managing aliases on one app, see Aliases below.
cipi-cli deploy <app> Trigger a 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> Structured deploy.php options (5.0.3+)
cipi-cli deploy audit <app> [--days N] Deploy audit ledger (5.4.0+)
cipi-cli yml <app> What applying the app's cipi.yml would change
cipi-cli yml plan <app> Same (aliases: show, status, diff)
cipi-cli yml apply <app> [-y] Apply it (async job: preview + confirmation unless -y)
cipi-cli yml auto <app> [on|off|status] Apply after every successful deploy (default: status)
The cipi.yml an app ships in its repository describes the server state it expects (aliases, www redirect, basic auth, redirects, proxies, PHP version and settings, limits, extra databases, workers, healthcheck, deploy options, crons, backups, post-deploy steps); these commands mirror cipi yml on the host and read the file of the live release, so commit it and deploy first.
yml plan prints the file, whether auto-apply is on, validation errors and warnings, the changes, the blockers (while any is listed, apply changes nothing) and what happens after the next deploy; it exits 1 when there is no file, it is not valid or something blocks the apply (--json prints the data and exits 0). yml apply previews the plan and asks before dispatching the app-yml-apply job (-y skips both), then prints the outcome — applied, unchanged, partial (with the failed changes), blocked, invalid or no-file — and exits 1 unless it is applied or unchanged; --json prints the job result as {"data": …}. yml auto <app> on covers CLI, panel and Git webhook deploys: anyone who can commit to the repository can then change the app's aliases, PHP settings, limits, workers, deploy recipe, scheduled commands, databases and backup schedule (for a Node app also its mode, Node version, build and start commands), so the CLI says so and asks for confirmation unless -y is passed.
Requires Cipi 5.6.4+, API 1.35+ and the yml-view (plan, auto status) / yml-manage (apply, auto on|off) token abilities — existing tokens do not get them: create a token with them (cipi api token create). Cipi 5.6.4 is also the release that applies cipi.yml on Git webhook deploys when auto-apply is on.
cipi-cli ssl install <app> Install Let's Encrypt certificate
cipi-cli ssl force <app> Re-apply HTTP → HTTPS redirect (4.8+)
cipi-cli www status <app> Show www/apex redirect status
cipi-cli www add <app> Add www/apex counterpart 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> Clear www canonical redirect
cipi-cli redirect list <app> List whole-app + path redirects (5.4.1+)
cipi-cli redirect set|unset|enable|disable <app>
cipi-cli redirect add|remove <app> Path redirects (--from, --to)
cipi-cli proxies list|add|remove <app> Prefix reverse proxies (5.4.1+)
Alias: redirects → redirect, proxy → proxies.
DNS for the app domain (and aliases) must already point to the server.
cipi-cli aliases list <app> List aliases
cipi-cli aliases add <app> <domain> Add an alias
cipi-cli aliases remove <app> <domain> [-y] Remove an alias
Alias: alias → aliases.
cipi-cli db engines List DB engines + default (4.8+)
cipi-cli db install <engine> Install an engine: mariadb|pgsql (5.0.6+)
cipi-cli db list List all databases
cipi-cli db create <name> [--engine] Create a database
cipi-cli db delete <name> [-y] Delete a database (API < 1.19 only)
cipi-cli db backup <name> Create a backup
cipi-cli db restore <name> [-y] Restore from backup
cipi-cli db password <name> [-y] Regenerate password and update .env
cipi-cli db anonymize <app> --email <addr> Request an anonymized dump via cipi/agent
cipi-cli db anonymize download <url> [-o F] Download the dump from the signed link
Aliases: database, dbs → db.
API 1.19+ removed database deletion and setting the default engine: use cipi db delete / cipi db default on the host.
db anonymize talks to the cipi/agent package installed in a Laravel app, not to the Cipi API: it 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. The agent runs the job in the app queue and emails a signed download link valid 15 minutes.
# one-time setup on the app
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/<user>/.db/anonymization.json
# request a dump, then download it from the link in the email
cipi-cli prod db anonymize myapp --email dev@example.com
cipi-cli db anonymize download "<signed url>" -o myapp.sql
cipi-cli db anonymize download "<signed url>" -o - | mysql -u root myapp_localAnonymize flags: --email / -e (prompted if omitted), --url (override the app base URL, e.g. when the app redirects to www), --token (override the bearer token)
Download flags: --output / -o (- for stdout), --force / -f (overwrite)
cipi-cli php list Installed versions, FPM status, default (5.0.6+)
cipi-cli php install <version> Install PHP 8.3 / 8.4 / 8.5
Switching the default PHP version and removing versions are host-only (cipi php switch|remove).
cipi-cli services list [name] System services and status (5.0.6+)
cipi-cli services restart <name> Restart a service (nginx, mariadb, …)
cipi-cli ssh-keys list Authorized keys of the cipi user (5.0.6+)
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
Aliases: service → services, ssh → ssh-keys.
cipi-cli smtp show Current SMTP config (password never shown, 5.0.7+)
cipi-cli smtp set [flags] Configure; omitted flags keep current 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, --port (587), --user, --password (required the first time), --from, --to, --tls (default on), --enabled (default on), --no-test
cipi-cli health list All configured app healthchecks (5.0.7+)
cipi-cli health show <app> One app's healthcheck and state
cipi-cli health set <app> [--url] [--expect] Enable/update (default https://<domain>/up, 200)
cipi-cli health unset <app> Disable
cipi-cli health check <app> Run now; exits 1 when unhealthy
cipi-cli status Global overview — one row per server
cipi-cli status <profile> Full details for one server
cipi-cli <profile> status Same, via profile prefix
Global columns: NAME, IP, CPU, RAM, HDD, APPS, SVC, CIPI.
Requires the API token ability status-view (GET /api/status, same data as cipi status on the host).
cipi-cli disk Disk usage: the server filesystem, then every app (GB and %)
cipi-cli disk db Every database per engine, in MB
Aliases: dbs, databases → disk db.
The figures of cipi disk on the host: an app is its home (releases, shared storage, logs) plus its database, largest first; the LIMIT column shows the soft limit set with cipi app limits <app> --disk=<GB> and flags apps over it. disk db lists MariaDB and PostgreSQL databases in MB, Valkey databases with their keys and memory, Meilisearch indexes with their documents. Sizes are measured by the server when asked, so the CLI waits up to three minutes. Requires Cipi 5.5.2+ (API sudoers), API 1.33+ and the disk-view ability.
cipi-cli jobs show <id> Show job status
cipi-cli jobs wait <id> Wait for a job to complete
cipi-cli run-commands List whitelisted app run binaries (5.0.3+)
Alias: job → jobs.
Most write commands wait for jobs automatically; use these to inspect a job by ID.
cipi-cli search status Meilisearch status (5.2.2+)
cipi-cli node list Installed Node runtimes (5.4.0+)
cipi-cli monitor System monitor checks (5.3.0+)
cipi-cli packages Optional host packages catalog
cipi-cli zt Cloudflare Zero Trust status (5.3.0+)
cipi-cli ip-whitelist show Show API client IP allowlist (5.0.8+)
cipi-cli ip-whitelist set <entries...> Replace whitelist (* = allow all)
cipi-cli ip-whitelist add|remove <ip>
cipi-cli ip-whitelist allow-all
cipi-cli api token add [profile] Add/update API token for a named profile
cipi-cli configure [--profile NAME] Add/update a server profile (endpoint + token)
cipi-cli profiles List configured servers
cipi-cli profiles list Same as bare profiles
cipi-cli profiles add [name] Add/update a server profile
cipi-cli profiles show [profile] Show one or all server profiles
cipi-cli profiles use <profile> Set the default server (alias: default)
cipi-cli profiles delete <profile> [-y] Delete a local server profile
Aliases:
servers/server→profilesprofiles use→profiles defaultconfigure list|show|delete|default→ prefer theprofilesequivalents
Always pass a profile name (prod, staging, …) when adding credentials — otherwise the CLI prompts for one.
cipi-cli update Update the CLI to the latest release
cipi-cli update --force Reinstall even if already up to date (allows downgrade)
Aliases: self-update, upgrade.
Downloads the matching binary from GitHub Releases (highest semver, not GitHub’s “latest” flag), verifies its SHA-256 checksum, and replaces the running binary in place. If installed in a system path (e.g. /usr/local/bin), run sudo cipi-cli update.
cipi-cli completion install Auto-detect shell and install completion
cipi-cli completion install --shell zsh Install for a specific shell (zsh|bash|fish)
cipi-cli completion zsh Print script only (same for bash / fish)
Writes the script under ~/.cipi/completions/ (or fish’s completions dir) and, for zsh/bash, appends a source line to your rc file. Reload the shell afterwards.
cipi-cli version Print version and build time
cipi-cli --help Root help
cipi-cli <command> --help Command help
| Flag | Description |
|---|---|
--json |
Output in JSON format (for scripting) |
--no-color |
Disable colored output |
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 cipi-cli jobs show <id> or cipi-cli jobs wait <id>.
Releases are automated via GitHub Actions. To publish a new version:
git tag v1.0.0
git push origin v1.0.0Prefer tags with a v prefix (v1.0.0). The pipeline builds binaries for Linux (amd64/arm64) and macOS (amd64/arm64), generates SHA-256 checksums, and creates a GitHub Release with all artifacts attached.
If a release is missing binaries, re-run the Release workflow manually from GitHub Actions (workflow dispatch) using the tag name.
make releaseThe Cipi server must have the API package installed and configured:
cipi api <domain>
cipi api ssl
cipi api token createSee the Cipi API documentation for details.
| Feature | Minimum Cipi | Minimum API |
|---|---|---|
| Suspend / unsuspend | 4.5.8 | 1.8.1 |
Rename primary domain (apps edit --domain) |
4.6.2 | 1.9.0 |
Multi-engine DB (db engines, --engine) |
4.8 | 1.12+ |
| WWW / SSL force | 4.8 | 1.12+ |
| Env / auth.json / artisan / run / deploy config | 5.0.3 | 1.14+ |
PHP / SSH keys / services / db install / webhook recreate |
5.0.6 | 1.15+ |
| SMTP / healthchecks | 5.0.7 | 1.15+ |
| IP whitelist | 5.0.8 | 1.15+ |
| Fix permissions | 5.2.1 | 1.31+ |
| Search (Meilisearch) / packages | 5.2.2 | 1.31+ |
| Monitor / Zero Trust | 5.3.0 | 1.31+ |
| Redirects / proxies (API sudoers) | 5.4.1 | 1.31+ |
| Node apps / deploy audit | 5.4.0 | 1.31+ |
Disk usage (disk, disk db) |
5.5.2 (API sudoers) | 1.33+ |
apps create --node-build, repository access check on create/edit |
5.6.0 | 1.34+ |
cipi.yml (yml plan, yml apply, yml auto) |
5.6.4 | 1.35+ (yml-view / yml-manage) |
Anonymized dumps (db anonymize) |
5.0.3 | 1.14+ (plus cipi/agent 1.1.1+ in the app) |
App logs (apps logs) |
— | 1.11.9 |
Server status (status) |
— | with GET /api/status + status-view |
Global domain map (domains) |
4.5.5 | — (built from /api/apps) |
| Aliases add/remove path | — | 1.31+ (/aliases/{domain}) |
New app PHP versions must be 8.3, 8.4, or 8.5 (Cipi 4.5.4+).
MIT