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, databases, SSL certificates, and deployments from any terminal. Binaries are available for Linux and macOS (amd64 and arm64).

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.2.5 (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

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

CLI Client

apps

Manage applications on your Cipi server.

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

# 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

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.

$ 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

CLI Client

deploy

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

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

$ cipi-cli ssl install myapp
Certificate provisioned for myapp.com

CLI Client

aliases

Manage domain aliases for an application.

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

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

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.

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

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.

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

$ cipi-cli update
Downloading cipi-cli v1.2.5...
Checksum verified. Updated to v1.2.5.

# 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).

$ 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: