PHP SDK

cipi/sdk is the PHP client for the Cipi panel API. From a Laravel app, a Symfony service, or a plain script, one Sanctum token calls the same REST surface as cipi-cli and the control panel: apps, deploys, domains, databases, and the server.

The SDK runs on your machine. It does not SSH into the VPS and it does not shell out to cipi. The server still needs the API package.

Install and enable the panel API first (cipi api), then create a token with cipi api token create. Grant only the abilities this application needs.

Install

bash
composer require cipi/sdk

Requires PHP 8.2+ with ext-curl and ext-json. Laravel is optional. Source: github.com/cipi-sh/sdk (MIT).


Client

Pass the panel origin and the token. Both https://api.example.com and https://api.example.com/api work. The client always calls /api/*.

php
use Cipi\Sdk\Cipi;

$cipi = Cipi::connect(
    baseUrl: 'https://api.example.com',
    token: getenv('CIPI_TOKEN') ?: '',
);

$apps = $cipi->apps()->list();

Reads return the JSON body as an associative array. Creates, edits, deploys, SSL, and most database writes return 202 with job_id. Poll that id, or let wait() do it.

php
$job = $cipi->deploys()->start('shop');
$result = $cipi->wait($job);

Plain http:// is rejected. For a panel on your laptop, opt in:

php
$cipi = Cipi::connect('http://127.0.0.1:8080', $token, [
    'allow_http' => true,
]);

Laravel

The service provider is discovered automatically on Laravel 11, 12, and 13. Publish the config if you want it in your app:

bash
php artisan vendor:publish --tag=cipi-config
dotenv
CIPI_BASE_URL=https://api.example.com
CIPI_TOKEN=
CIPI_TIMEOUT=30
CIPI_ALLOW_HTTP=false
php
use Cipi\Sdk\Laravel\Facades\Cipi;

$apps = Cipi::apps()->list();

You can also type-hint Cipi\Sdk\Cipi in a controller or job. The container holds one server. For a second server, call Cipi::connect() with that server's URL and token — do not reuse the facade.

Symfony, Slim, and other frameworks use the same Cipi::connect() call and register the instance in their own container. There is no extra bundle.

With cipi/agent: when the SDK is installed next to cipi/agent 2.0 and CIPI_BASE_URL / CIPI_TOKEN are set, the app's MCP server gains panel_rollback, panel_deploy_audit, panel_db_backup, panel_job and panel_status. Both packages read config/cipi.php and both publish under cipi-config; the agent also offers --tag=cipi-agent-config.

Apps

App creates accept the same fields as POST /api/apps: user and domain are required. Add repository and branch for Git, php, custom, octane, engine, node_build (Laravel asset build), env (environment label), or the Node fields node, framework, node_version, build, start, output, and health_path.

php
$cipi->apps()->list();
$cipi->apps()->get('shop');

$cipi->wait($cipi->apps()->create([
    'user' => 'shop',
    'domain' => 'shop.example.com',
    'repository' => 'git@github.com:acme/shop.git',
    'branch' => 'main',
    'php' => '8.4',
    'node_build' => 'npm ci && npm run build',
]));

$cipi->apps()->update('shop', ['php' => '8.4']);
$cipi->apps()->suspend('shop');
$cipi->apps()->unsuspend('shop');
$cipi->apps()->fixPermissions('shop');
$cipi->apps()->recreateWebhook('shop', rotateSecret: true);
$cipi->apps()->delete('shop');

$cipi->limits()->get('shop');
$cipi->wait($cipi->limits()->update('shop', [
    'fpm_max_children' => 10,
    'disk_limit_gb' => 5,
]));

node_build is the asset build Cipi runs inside every deploy of a Laravel app, before the release goes live. It starts with npm, npx, yarn, pnpm, bun, or node, allows && and ;, refuses pipes, redirects, backticks, and $( ), and is at most 200 characters. The panel answers 422 (ValidationException) on a bad command or on a custom or Node app; Node apps take build. Needs cipi/api 1.34.0+ and Cipi CLI 5.6.0+.

The same versions check that the app's deploy key can read its repository. The app-create result, and the app-edit result when the repository or branch changed, carry repository_access; app-create also carries build. The check never fails the job, so read it after wait():

php
$job = $cipi->wait($cipi->apps()->create($attributes));
$access = $job['data']['result']['repository_access'] ?? null;

if ($access !== null && $access['status'] !== 'ok') {
    // $access['error']: the git line. $access['hint']: the CLI fix, e.g.
    // cipi git github-token <token> && cipi git refresh shop
}

status is ok (readable, the branch exists), nobranch (readable, no such branch), or denied (the key cannot read it). branch, error, and hint are optional. On older servers, and on apps without a repository, repository_access is absent.

env is the app's environment label, production by default: staging, preview-42, and so on. Lowercase letters, digits, - and _, 1 to 32 characters, starting with a letter or digit (^[a-z0-9][a-z0-9_-]{0,31}$); anything else is a 422 (ValidationException). Set it on create, change it with update(), and read it from list() and get(). It decides which cipi.yml the app reads. Needs cipi/api 1.36.0+ and Cipi CLI 5.8.0+: an older panel ignores the attribute and omits the key, so treat a missing env as production.

php
$cipi->apps()->create([
    'user' => 'shop',
    'domain' => 'staging.shop.example.com',
    'repository' => 'git@github.com:acme/shop.git',
    'branch' => 'develop',
    'env' => 'staging',
]);

$cipi->apps()->update('shop', ['env' => 'preview']);

$env = $cipi->apps()->get('shop')['data']['env'] ?? 'production';

limits() reads and sets FPM children, memory_limit, Octane workers, queue workers, and the soft disk limit (disk_limit_gb, files plus database). The update is a job. Pass disk_limit_gb as null to remove it. Node apps accept only that key. The disk limit needs Cipi CLI 5.5.0+; it warns, it does not block the app.

HTTP Basic Auth, Artisan, and whitelisted app commands:

php
$cipi->basicAuth()->enable('shop', 'admin');
$cipi->basicAuth()->disable('shop');

$cipi->wait($cipi->artisan()->run('shop', 'migrate --force'));
$cipi->run()->commands();
$cipi->wait($cipi->run()->execute('shop', 'composer install --no-dev'));

artisan() and run() are async jobs. The panel rejects tinker and interactive programs. logs()->get($app, $type, $page, $perPage) reads nginx, php, worker, deploy, or laravel (or omit the type for all).


Deploy and jobs

php
$cipi->wait($cipi->deploys()->start('shop'));
$cipi->deploys()->rollback('shop');
$cipi->deploys()->unlock('shop');
$cipi->deploys()->audit('shop', days: 30);

$cipi->deployConfig()->get('shop');
$cipi->deployConfig()->update('shop', [
    'keep_releases' => 5,
    'migrate' => true,
]);

wait() polls until completed or failed. The default timeout is 300 seconds. A failed job throws Cipi\Sdk\Exception\JobFailedException and keeps the job payload on $e->job. Pass a job id or the 202 body:

php
$cipi->jobs()->get('9f1c…');
$cipi->jobs()->wait($job, timeoutSeconds: 120, intervalSeconds: 1.0);

Deploy config edits the structured Deployer options and regenerates deploy.php. It does not upload a raw PHP file. The audit call is synchronous and reads the hash-chained ledger (Cipi 5.4.0+).

A deploy can be watched while it runs, and the past ones read back:

php
$status = $cipi->deploys()->status('shop', tail: 50)['data'];
$status['state'];   // running, queued, interrupted or idle
$status['tail'];    // the last 50 lines of the deploy log

$cipi->deploys()->history('shop', limit: 10);
$cipi->deploys()->last(); // the last run of every app, null for one never deployed

All three are synchronous. status() needs the deploy-manage ability, cipi/api 1.37.0+ and Cipi CLI 5.8.4+; tail is 0 to 500 lines. history() and last() need apps-view or deploy-manage, cipi/api 1.39.0+ and Cipi CLI 5.9.0+; limit is 1 to 500, 30 when omitted.

An app can ship a cipi.yml in its repository that describes the server state it expects. yml() reads its status and plan, applies it, and turns auto-apply on or off:

php
$plan = $cipi->yml()->status('shop')['data'];
$env = $plan['env'] ?? 'production'; // the file is cipi-<env>.yml, or cipi.yml

foreach ($plan['changes'] as $change) {
    echo $change['summary'], PHP_EOL; // e.g. "PHP 8.3 → 8.4"
}

if ($plan['blockers'] === []) {
    $job = $cipi->jobs()->wait($cipi->yml()->apply('shop'), throwOnFailure: false);
    $outcome = $job['data']['result']['outcome'];
}

$cipi->yml()->enableAuto('shop');
$cipi->yml()->disableAuto('shop');

status() is synchronous. file is null when the live release has no cipi.yml; valid is false when it does not parse (see errors); in_sync is true when nothing would change. Each entry in changes has a machine kind and a human summary; show the summary. apply() is a job (app-yml-apply) and changes nothing while blockers is not empty. Its result.outcome is applied or unchanged (job completed), or partial, blocked, invalid, or no-file (job failed, same result with applied, failed, failures, blockers, errors). wait() throws JobFailedException on those; pass throwOnFailure: false to jobs()->wait() to read the result instead.

With cipi/api 1.36.0+ and Cipi CLI 5.8.0+ the file follows the app's env label: the server reads cipi-<env>.yml first (cipi-staging.yml for staging) and falls back to cipi.yml, and status() returns env next to file so you can tell which one it picked. Older panels omit env; treat it as production. The same versions accept deploy.branch in the file, the Git branch the app deploys, validated like cipi app edit --branch (letters, digits, ., _, /, -, no ..); a branch that differs from the app's is one of the changes.

Auto-apply: enableAuto() applies cipi.yml after every successful deploy (CLI, panel, and Git webhook). Anyone who can commit to the repository can then change this app's aliases, PHP settings, limits, workers, deploy recipe, scheduled commands, databases, and backup schedule (for Node apps also mode, version, build, and start). Ask for confirmation before turning it on for someone. enableAuto() and disableAuto() are synchronous and idempotent.

Reads need the yml-view ability, writes yml-manage. Existing tokens do not get them automatically: a token without them gets AuthorizationException (403), so catch it and treat cipi.yml as unavailable. Needs cipi/api 1.35.0+ and Cipi CLI 5.6.4+. A host with an older CLI returns 503; a panel older than 1.35.0 has no such route (404). Before Cipi 5.6.4 a webhook deploy never applied cipi.yml, even with auto-apply on.


Domains and SSL

php
$cipi->aliases()->add('shop', 'www.shop.example.com');
$cipi->www()->forceToRoot('shop');

$cipi->redirects()->set('shop', 'https://example.com', 301, keepPath: true);
$cipi->redirects()->add('shop', '/blog/', 'https://blog.example.com', 301, true);
$cipi->redirects()->remove('shop', '/blog/');

$cipi->proxies()->add(
    'shop',
    prefix: '/api/',
    upstream: 'http://127.0.0.1:3000',
    stripPrefix: true,
);

$cipi->ssl()->install('shop');
$cipi->ssl()->install('shop', dns: 'cloudflare', account: 'prod', wildcard: true);
$cipi->ssl()->force('shop');

$cipi->ssl()->dnsAccounts();
$cipi->ssl()->setDnsAccount($cloudflareToken, 'prod');
$cipi->ssl()->removeDnsAccount('prod');

ssl()->install() with no options reissues the certificate as it was last issued. DNS-01 (dns: 'cloudflare'), wildcard, and http: true (back to HTTP-01) need Cipi CLI 5.5.0+; reissuing DNS-01 with an empty body needs 5.5.1. setDnsAccount() is synchronous, so the token is not queued and is never returned. removeDnsAccount() returns 409 while a certificate still renews with that account.

Redirect and proxy writes are synchronous on the panel: Nginx is tested and the previous vhost is restored if the test fails. The proxy loopback guard cannot be bypassed from the API. Node apps use node()->runtimes(), node()->status($app), and node()->restart($app) (restart is a job).


Env, auth, and databases

env() merges keys. It does not replace the file. authJson() is the shared Composer auth.json, not HTTP Basic Auth. Both need Cipi 5.0.3+ and the matching token ability (apps-env, apps-auth).

php
$cipi->env()->update('shop', [
    'APP_ENV' => 'production',
], ['TELESCOPE_ENABLED']);

$cipi->authJson()->create('shop');
$cipi->authJson()->replace('shop', [
    'http-basic' => [
        'repo.example.com' => ['username' => 'token', 'password' => $secret],
    ],
]);
php
$cipi->databases()->engines();
$cipi->databases()->list('pgsql');
$cipi->wait($cipi->databases()->create('shop', 'pgsql'));
$cipi->databases()->backup('shop');
$cipi->databases()->restore('shop', '/home/cipi/backups/shop.sql.gz');
$cipi->databases()->password('shop');

engine is mariadb or pgsql. Omit it to use the server default. Backup, restore, and password regeneration are jobs. The restore path has to be a .sql.gz file already on the server.

A database can belong to an app, and a dump on your machine can be restored without copying it to the server first:

php
$cipi->wait($cipi->databases()->create('shop_reports', 'pgsql', app: 'shop'));
$cipi->databases()->link('legacy', 'shop');
$cipi->databases()->unlink('legacy');

$cipi->wait($cipi->databases()->restoreLocal('shop', __DIR__.'/shop.sql.gz'));

A linked database shows under its app (apps()->list() returns each app's databases) and list() returns app, link and size_mb for each one. link() and unlink() are synchronous.

restoreLocal() sends a .sql or .sql.gz file in chunks and starts the restore job on it. The file is read one chunk at a time, so its size is not bound by memory_limit. If a chunk or the restore call is refused, the partial upload is cancelled before the exception reaches you. The steps are available one by one:

php
$cipi->databases()->uploadLimits();                       // max size, chunk size, what may wait
$upload = $cipi->databases()->upload('/tmp/shop.sql.gz'); // start + every chunk
$cipi->wait($cipi->databases()->restoreUpload('shop', $upload['data']['upload_id']));

$cipi->databases()->startUpload('shop.sql.gz', $bytes);
$cipi->databases()->uploadChunk($uploadId, 0, $firstChunk);
$cipi->databases()->cancelUpload($uploadId);

The panel deletes an uploaded dump when its restore job ends, or after a day. Links and uploads need the dbs-manage ability, cipi/api 1.39.0+ and Cipi CLI 5.9.0+; an older host returns 503.

Backups

php
$backups = $cipi->backups()->status()['data'];
$backups['uncovered']; // apps and databases no enabled profile takes

$cipi->backups()->createProfile('nightly', [
    'scope' => 'all',            // all, files or db
    'every' => '1d',             // or 'cron' => '0 3 * * *'
    'destinations' => ['s3'],    // local, s3 or a named destination
    'keep_days' => 14,
    'encrypt' => true,
]);
$cipi->backups()->updateProfile('nightly', ['keep_days' => 30]);
$cipi->backups()->disableProfile('nightly');
$cipi->backups()->enableProfile('nightly');
$cipi->backups()->deleteProfile('nightly');

$cipi->backups()->run('nightly');             // omit the profile to run every enabled one
$cipi->backups()->runs('nightly');
$cipi->wait($cipi->backups()->verify('nightly'));
$cipi->backups()->testDestinations();

run() is not a job: the panel answers 202 with started: true as soon as the run has started, and the outcome shows in status() (running, then the profile's last run). Do not pass its answer to wait(). verify() is a job (backup-verify). Everything else is synchronous. A profile also takes apps, databases, exclude_databases, exclude_tables, keep and keep_weeks. Destinations and their credentials are configured on the server with cipi backup configure and are never returned.

Reads need the backups-view ability, writes backups-manage; both need cipi/api 1.39.0+ and Cipi CLI 5.9.0+. Existing tokens do not get them automatically.


Server

php
$cipi->server()->status();
$cipi->php()->list();
$cipi->php()->install('8.4');
$cipi->ssh()->add($publicKey);
$cipi->ssh()->remove(2);
$cipi->services()->list();
$cipi->services()->restart('php8.4-fpm');

$cipi->smtp()->get();
$cipi->health()->update('shop', 'https://shop.example.com/health', 200);
$cipi->health()->check('shop');
$cipi->search()->enable('shop');

$cipi->packages()->list();
$cipi->monitor()->list();
$cipi->zeroTrust()->status();

$cipi->disk()->usage();
$cipi->disk()->databases();

Packages, the system monitor, Cloudflare Zero Trust, and disk usage are read-only here, matching the panel API. Installing those pieces stays on the host CLI. disk() needs Cipi CLI 5.5.2 (older hosts return 503). Sizes are measured on request. The per-app soft limit is limits(), not disk().

Node runtimes are installed, upgraded, and removed as jobs:

php
$cipi->wait($cipi->node()->install(24));
$cipi->wait($cipi->node()->upgrade(24, restart: true)); // omit the major to upgrade every runtime
$cipi->wait($cipi->node()->setDefault(24));             // or 'system'
$cipi->wait($cipi->node()->remove(20));

They need the node-runtimes-manage ability, cipi/api 1.39.0+ and Cipi CLI 5.9.0+. Existing tokens do not get the ability automatically.

The API allowlist defaults to *. Restrict it without locking yourself out — ensure_client_ip: true keeps the caller on the list:

php
$cipi->ipWhitelist()->replace(['203.0.113.10'], ensureClientIp: true);
$cipi->ipWhitelist()->add('203.0.113.11');
$cipi->ipWhitelist()->allowAll();

An endpoint this release does not wrap yet is still reachable:

php
$cipi->request('GET', '/apps/shop');

Security

  • HTTPS and certificate verification are on. Redirects are not followed, so the Bearer token stays on the host you configured.
  • The token is sent only in the Authorization header. A value that contains whitespace or control characters is rejected, which blocks header injection.
  • The token is stripped from exception messages, decoded bodies, and var_dump / print_r output.
  • GET may retry 429 and 503 when Retry-After is at most 10 seconds. Writes are never retried.
  • Responses larger than 16 MiB are refused. Timeouts default to 30 seconds (10 seconds to connect).

The third argument of Cipi::connect() changes those limits. On Laravel the package config reads CIPI_TIMEOUT, CIPI_CONNECT_TIMEOUT, CIPI_MAX_RETRIES, and CIPI_ALLOW_HTTP. A value out of range throws before any request is sent.

php
$cipi = Cipi::connect($url, $token, [
    'timeout' => 30,                  // 1–300 seconds
    'connect_timeout' => 10,          // 1–60 seconds
    'max_retries' => 2,               // 0–5, reads only
    'max_response_bytes' => 16777216, // 1 KiB–64 MiB
    'allow_http' => false,
]);

Keep CIPI_TOKEN in the environment of the PHP host. Do not commit it. Create one token per application, with the smallest ability set that still works (apps-view, deploy-manage, dbs-create, …). A missing ability is HTTP 403, not a silent no-op.


Errors

HTTP failures throw Cipi\Sdk\Exception\CipiException or a subclass. The status, the JSON body, the method, and the path are on the exception. The token is not.

Status Exception
401 AuthenticationException
403 AuthorizationException — missing ability, or IP whitelist
404 NotFoundException
409 ConflictException
422 ValidationException — errors() when the panel returned a Laravel bag
429 RateLimitException
5xx ServerException

Without an HTTP status: TransportException when the connection or the TLS handshake fails, or a response is over the size limit; ConfigurationException for an invalid URL, token, path, or option, before anything is sent. wait() adds JobFailedException when the job ends failed and TimeoutException when it is still running at the timeout. RateLimitException carries retryAfter in seconds when the panel sent it.

php
use Cipi\Sdk\Exception\AuthorizationException;
use Cipi\Sdk\Exception\JobFailedException;

try {
    $cipi->wait($cipi->deploys()->start('shop'));
} catch (JobFailedException $e) {
    $job = $e->job;
} catch (AuthorizationException $e) {
    // token is missing deploy-manage
}