Cipi Docs — CLI Client

CLI Client

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 v0.1.1 (linux/amd64)

CLI Client

Configuration

Before using cipi-cli, connect it to your Cipi API server. You need the API endpoint URL and a Sanctum token created with cipi api token create on your server.

Interactive setup

bash

$ cipi-cli configure
API endpoint: https://api.example.com
Token: 1|yourtoken...
Configuration saved to ~/.cipi/config.json

Non-interactive setup

bash

$ cipi-cli configure --endpoint https://api.example.com --token "1|yourtoken..."

Show current configuration

bash

$ cipi-cli configure show
Endpoint: https://api.example.com
Token:    1|a8Kz••••••••

Credentials are stored in ~/.cipi/config.json with permissions 0600.

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

Create flags

--name 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 Change primary domain

Examples

bash

# List all apps
$ cipi-cli apps list

# Create a Laravel app
$ cipi-cli apps create --name=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 --name=landing --domain=landing.acme.com \
    --custom --docroot=dist

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

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

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

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.

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)

bash

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

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

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

CLI Client

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

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)

bash

$ cipi-cli jobs show 42
Job #42: deploy myapp — completed

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

CLI Client

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.