Installazione di cipi-cli

cipi-cli è un binary Go standalone che comunica con la REST API di Cipi dalla tua macchina locale. Nessun SSH richiesto — gestisci app, database, certificati SSL e deployment da qualsiasi terminale. I binary sono disponibili per Linux e macOS (amd64 e arm64).

Il server Cipi deve avere il package API installato e configurato prima di usare cipi-cli. Vedi cipi api per le istruzioni di setup.

Scarica il binary

Scarica l'ultima release per la tua piattaforma dalla pagina Releases, poi:

bash
chmod +x cipi-cli-*
sudo mv cipi-cli-* /usr/local/bin/cipi-cli

Compila dal sorgente

bash
git clone https://github.com/cipi-sh/cli.git
cd cli
make build
sudo make install

Verifica l'installazione

bash
$ cipi-cli version
cipi-cli v1.2.5 (linux/amd64)

Configurazione

Un profilo è una connessione nominata a un server Cipi (endpoint API + token). Usa quanti profili hai server — ad esempio prod, staging o client-a. Ti servono l'URL dell'endpoint API e un token Sanctum creato con cipi api token create su ogni server.

Le credenziali sono salvate per profilo in ~/.cipi/config.json con permessi 0600. Passa sempre un nome profilo — se lo ometti, la CLI chiede quale usare invece di scrivere silenziosamente su default.

Setup interattivo

Consigliato: salva il token con api token add. Helper equivalenti sono configure --profile e profiles add:

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

Setup non interattivo

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

Mostra configurazione

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

profiles

Gestisci più connessioni server da un'unica installazione cipi-cli. Un profilo corrisponde a un server. Prefissa qualsiasi comando con un nome profilo per puntare a quel server, oppure imposta un default con profiles use per omettere il prefisso. Gli alias servers / server funzionano come profiles.

Puntare a un server

bash
$ cipi-cli prod apps list
$ cipi-cli staging apps show myapp
$ cipi-cli prod deploy myapp
$ cipi-cli prod ssl install myapp

Con un server default impostato, puoi eseguire comandi senza prefisso:

bash
$ 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
Comando Descrizione
cipi-cli api token add [profile] Aggiungi o aggiorna endpoint API + token per un profilo server nominato
cipi-cli profiles Elenca i server configurati (alias: cipi-cli servers)
cipi-cli profiles add [name] [flags] Aggiungi o aggiorna un profilo server (come configure --profile)
cipi-cli profiles list Elenca i server configurati
cipi-cli profiles show [profile] Mostra un profilo server, o tutti se omesso
cipi-cli profiles use <profile> Imposta il server default (alias: profiles default)
cipi-cli profiles delete <profile> [-y] Elimina un profilo server locale (solo credenziali — nulla cambia sul server remoto)

api token add, profiles add e configure accettano gli stessi flag: --endpoint e --token (più --profile quando il nome non è posizionale).

Alias: servers / serverprofiles; profiles useprofiles default. Gli stessi comandi di gestione sono disponibili anche sotto cipi-cli configure list, configure show, configure default e configure delete — preferisci profiles o api token add per salvare le credenziali.

apps

Gestisci le applicazioni sul tuo server Cipi.

Comando Descrizione
cipi-cli apps list Elenca tutte le applicazioni
cipi-cli apps show <name> Mostra i dettagli dell'applicazione
cipi-cli apps create [flags] Crea una nuova applicazione
cipi-cli apps edit <name> [flags] Modifica un'applicazione
cipi-cli apps delete <name> [-y] Elimina un'applicazione
cipi-cli apps suspend <name> Metti un'app offline (pagina manutenzione HTTP 503) senza eliminarla
cipi-cli apps unsuspend <name> Ripristina un'app sospesa al servizio normale
cipi-cli apps logs <name> [flags] Leggi log applicazione paginati (nginx, PHP-FPM, Laravel, worker, deploy)

Flag create

--user Nome applicazione (usato come utente Linux e nome database)
--domain Dominio primario dell'applicazione
--php Versione PHP (es. 8.5)
--repository URL repository Git
--branch Branch Git da cui fare deploy
--custom Crea un'app custom (non Laravel) con deploy htdocs
--docroot Document root relativa a htdocs (solo app custom)

Flag edit

--php Cambia versione PHP
--repository Aggiorna URL repository Git
--branch Cambia branch di deploy
--domain Rinomina il dominio primario (richiede Cipi 4.6.2+ e API 1.9.0+)

Flag logs

--type Filtro tipo log: all (default), nginx, php, worker, deploy o laravel
--page Numero pagina, a partire da 1 per le righe più recenti (default 1)
--per-page Righe per file log per pagina (default 50, max 1000; richiede API 1.11.9+)

Esempi

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

Elenca ogni dominio primario e alias su tutte le app del server in un'unica tabella — l'equivalente remoto di cipi domains sul server. Utile per auditare la copertura DNS o individuare domini senza SSL prima del rinnovo certificato.

Comando Descrizione
cipi-cli domains Elenca ogni dominio e alias su tutte le app
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
La mappa domini globale è costruita da GET /api/apps sul server. Richiede Cipi 4.5.5+ sul server (per i dati sottostanti di cipi domains) ma nessuna versione minima del package API.

deploy

Attiva deployment, rollback alla release precedente o sblocca un deployment bloccato.

Comando Descrizione
cipi-cli deploy <app> Attiva un deploy zero-downtime
cipi-cli deploy rollback <app> [-y] Rollback alla release precedente
cipi-cli deploy unlock <app> Sblocca un deploy bloccato
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

Installa certificati Let's Encrypt per le tue applicazioni.

Comando Descrizione
cipi-cli ssl install <app> Installa certificato Let's Encrypt (copre dominio primario e tutti gli alias)
bash
$ cipi-cli ssl install myapp
Certificate provisioned for myapp.com

aliases

Gestisci alias di dominio per un'applicazione.

Comando Descrizione
cipi-cli aliases list <app> Elenca tutti gli alias di un'app
cipi-cli aliases add <app> <domain> Aggiungi un alias di dominio
cipi-cli aliases remove <app> <domain> [-y] Rimuovi un alias di dominio
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

Gestisci database MariaDB.

Comando Descrizione
cipi-cli db list Elenca tutti i database
cipi-cli db create <name> Crea un database
cipi-cli db delete <name> [-y] Elimina un database
cipi-cli db backup <name> Crea un backup del database
cipi-cli db restore <name> [-y] Ripristina database da backup
cipi-cli db password <name> [-y] Rigenera password e aggiorna .env
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.

status

Leggi lo stesso snapshot host di cipi status sul server — via GET /api/status. status nudo mostra una panoramica globale (una riga per server configurato). Passa un nome profilo (o usa un prefisso profilo) per i dettagli completi.

Comando Descrizione
cipi-cli status Panoramica globale — una riga per server (alias: status all)
cipi-cli status <profile> Dettagli completi per un server
cipi-cli <profile> status Stessa vista dettaglio, via prefisso profilo

Colonne globali: NAME, IP, CPU, RAM, HDD, APPS, SVC, CIPI. Il profilo default è contrassegnato con *.

bash
$ 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
Richiede l'ability del token API status-view e GET /api/status sul server (API 1.11.6+). Crea o ruota il token con cipi api token create e includi status-view.

jobs

Le operazioni di scrittura (create, edit, delete, deploy, SSL, ecc.) sono asincrone sulla Cipi API. La CLI fa polling automatico per il completamento del job e mostra uno spinner in attesa. Se preferisci gestire il polling manualmente, usa i comandi jobs.

Comando Descrizione
cipi-cli jobs show <id> Mostra stato job
cipi-cli jobs wait <id> Attendi il completamento di un job (bloccante)
bash
$ cipi-cli jobs show 42
Job #42: deploy myapp — completed

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

update

Aggiorna cipi-cli all'ultima release da GitHub. Il comando sceglie la semver più alta tra le release pubblicate (non il flag "latest" di GitHub, che può puntare a un tag più vecchio), scarica il binary corrispondente per la tua piattaforma, ne verifica il checksum SHA-256 e sostituisce il binary in esecuzione al posto. Alias: self-update, upgrade.

Comando Descrizione
cipi-cli update Aggiorna alla semver pubblicata più alta
cipi-cli update --force Reinstalla anche se già aggiornato (consente downgrade)
bash
$ 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

completion

Installa autocompletamento shell per cipi-cli. Il percorso consigliato è completion install, che rileva la tua shell, scrive lo script di completamento e lo aggancia al file rc (idempotente).

Comando Descrizione
cipi-cli completion install Rileva shell e installa completamento automaticamente
cipi-cli completion install --shell zsh Installa per una shell specifica (zsh, bash o fish)
cipi-cli completion zsh Stampa lo script di completamento zsh su stdout
cipi-cli completion bash Stampa lo script di completamento bash su stdout
cipi-cli completion fish Stampa lo script di completamento fish su stdout
bash
$ 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

Per zsh e bash, lo script è scritto sotto ~/.cipi/completions/ e una riga source è aggiunta al file rc della shell. Per fish, lo script va in ~/.config/fish/completions/ (auto-caricato). Ricarica la shell dopo, poi prova cipi-cli <TAB>.


Flag globali

Questi flag sono disponibili su tutti i comandi.

--json Output in formato JSON — utile per scripting e pipeline CI/CD
--no-color Disabilita output colorato
--help Mostra aiuto per qualsiasi comando
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

Release

Le release sono automatizzate via GitHub Actions. Binary precompilati per Linux (amd64/arm64) e macOS (amd64/arm64) sono pubblicati con checksum SHA-256 sulla pagina GitHub Releases.

Codice sorgente

cipi-cli è open source, licenza MIT, scritto in Go. Contributi benvenuti su GitHub.


Requisiti

Il server Cipi deve avere il package API installato e configurato prima di usare cipi-cli:

bash
$ cipi api <domain>
$ cipi api ssl
$ cipi api token create

Le versioni PHP per nuove app devono essere 8.3, 8.4 o 8.5 (Cipi 4.5.4+). Alcune funzionalità CLI dipendono da versioni specifiche di server e API:

Funzionalità Cipi minimo API minima
Sospendi / riattiva (apps suspend) 4.5.8 1.8.1
Rinomina dominio primario (apps edit --domain) 4.6.2 1.9.0
Log app (apps logs) 1.11.9
Stato server (status) GET /api/status + status-view (1.11.6+)
Mappa domini globale (domains) 4.5.5 — (costruita da /api/apps)