Installation

cipi-cli is a standalone Go binary that talks to the Cipi REST API from your local machine. No SSH required — manage apps, databases, SSL certificates, and deployments 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.0.1 (linux/amd64)

Configuration

Before using cipi-cli, connect it to your Cipi API server. Each profile maps to one server — use separate profiles for production, staging, or any other environment. You need the API endpoint URL and a Sanctum token created with cipi api token create on your server.

Credentials are stored per profile in ~/.cipi/config.json with permissions 0600. If you omit --profile, the profile name defaults to default.

Interactive setup

bash
$ cipi-cli configure --profile prod
Cipi API endpoint: https://api.example.com
API token: 1|yourtoken...
Profile "prod" saved to ~/.cipi/config.json

$ cipi-cli configure --profile staging
Cipi API endpoint: https://staging-api.example.com
API token: 1|stagingtoken...
Profile "staging" saved to ~/.cipi/config.json

Non-interactive setup

bash
$ cipi-cli configure --profile prod \
    --endpoint https://api.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 profiles

profiles

Manage multiple server connections from a single cipi-cli installation. Prefix any command with a profile name to target that server, or set a default profile to omit the prefix.

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 profile set, you can run commands without the prefix:

bash
$ cipi-cli profiles default prod
Default profile set to "prod"

$ cipi-cli apps list
# Uses the prod profile
Command Description
cipi-cli profiles List configured profiles
cipi-cli profiles list List configured profiles
cipi-cli profiles show [profile] Show one profile, or all if omitted
cipi-cli profiles default <profile> Set the default profile
cipi-cli profiles delete <profile> [-y] Delete a profile
The same profile subcommands are also available under cipi-cli configure list, configure show, configure default, and configure delete.

apps

Manage applications on your Cipi server.

Command Description
cipi-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> 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)

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
--custom Create a custom (non-Laravel) app with htdocs deploy
--docroot Document root relative to htdocs (custom apps only)

Edit flags

--php Change PHP version
--repository Update Git repository URL
--branch Change deploy branch
--domain Rename the primary domain (requires Cipi 4.6.2+ and API 1.9.0+)

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

# 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

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

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
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)
bash
$ cipi-cli ssl install myapp
Certificate provisioned for myapp.com

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 databases.

Command Description
cipi-cli db list List all databases
cipi-cli db create <name> Create a database
cipi-cli db delete <name> [-y] Delete a database
cipi-cli db backup <name> Create a database backup
cipi-cli db restore <name> [-y] Restore database from backup
cipi-cli db password <name> [-y] Regenerate database password
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.

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 latest release from GitHub. The command downloads the matching binary for your platform, verifies its SHA-256 checksum, and replaces the running binary in place.

Command Description
cipi-cli update Update to the latest release
cipi-cli update --force Reinstall even if already up to date
bash
$ cipi-cli update
Downloading cipi-cli v1.0.1...
Checksum verified. Updated to v1.0.1.

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

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
Global domain map (domains) 4.5.5 — (built from /api/apps)