static-php-cli/docs/en/guide/cli-reference.md

outline

outline
deep

CLI Reference

::: tip If you installed spc as a pre-built binary, replace every spc in this page with ./spc (or .\spc.exe on Windows).

If you installed from source, use bin/spc instead. :::

download

Download source archives and pre-built binaries required for building.

spc download [artifacts] [options]

artifacts (optional): Specific artifacts to download, comma-separated (e.g. "php-src,openssl,curl").

Options

Option	Short	Description
--for-extensions=<list>	-e	Download artifacts needed by the given extensions
--for-libs=<list>	-l	Download artifacts needed by the given libraries
--for-packages=<list>		Download artifacts needed by the given packages
--without-suggests		Skip suggested packages when using --for-extensions
--clean		Delete existing download cache before fetching
--with-php=<ver>		PHP version in major.minor format (default: 8.4)
--prefer-binary	-p	Prefer pre-built binaries over source archives
--prefer-source		Prefer source archives over pre-built binaries
--source-only		Only download source artifacts
--binary-only		Only download binary artifacts
--parallel=<n>	-P	Number of parallel downloads (default: 1)
--retry=<n>	-R	Number of retries on failure (default: 0)
--ignore-cache=<list>		Force re-download the specified artifacts
--no-alt		Do not use alternative mirror URLs
--no-shallow-clone		Do not clone git repositories shallowly
--custom-url=<src:url>	-U	Override the download URL for a source
--custom-git=<src:branch:url>	-G	Override with a custom git repository
--custom-local=<src:path>	-L	Use a local path as a source override

Examples

# Download only what the chosen extensions need
spc download --for-extensions="bcmath,openssl,curl" --with-php=8.4

# Download specific artifacts
spc download "php-src,openssl"

# Speed up with parallelism and retries
spc download --for-extensions="bcmath,openssl,curl" --parallel 8 --retry=3

# Prefer pre-built binaries
spc download --for-extensions="bcmath,openssl,curl" --prefer-binary

# Force re-download the PHP source (e.g. when switching versions)
spc download --for-extensions="bcmath,curl" --ignore-cache="php-src" --with-php=8.3

# Override a download URL
spc download --for-extensions="bcmath" --custom-url "php-src:https://downloads.php.net/~user/php-8.5.0alpha1.tar.xz"

build:php

Build PHP and extensions from source. Alias: build.

spc build:php <extensions> [options]

extensions (required): Comma-separated list of extensions to compile statically (e.g. "bcmath,openssl,curl").

All download options are also available on build:php with the --dl- prefix (e.g. --dl-with-php=8.3, --dl-parallel=4). These are passed to the automatic downloader that runs before the build.

SAPI Selection

These flags apply only to the combined build:php target. To build a specific SAPI in isolation, use its dedicated command (e.g. spc build:php-cli).

Option	Description
--build-cli	Build the cli SAPI (php / php.exe)
--build-fpm	Build php-fpm (Linux and macOS only)
--build-cgi	Build php-cgi
--build-micro	Build micro.sfx
--build-embed	Build the embed static library (libphp.a / php8embed.lib)
--build-frankenphp	Build the FrankenPHP binary

Common Build Options

Option	Short	Description
--no-strip		Keep debug symbols; do not strip the binary
--with-upx-pack		Compress the output binary with UPX (install first with spc install-pkg upx; Linux and Windows only)
--disable-opcache-jit		Disable OPcache JIT
--with-config-file-path=<path>		Directory where PHP looks for php.ini (default: /usr/local/etc/php)
--with-config-file-scan-dir=<path>		Directory PHP scans for additional .ini files (default: /usr/local/etc/php/conf.d)
--with-hardcoded-ini=<k=v>	-I	Bake an INI setting into the binary at compile time (repeatable)
--enable-zts		Enable thread-safe (ZTS) mode
--no-smoke-test		Skip the post-build smoke tests
--with-suggests	-L / -E	Also resolve and install suggested packages
--with-packages=<list>		Additional packages to install alongside the build
--no-download		Skip the download step (use existing cached files)
--with-added-patch=<file>	-P	Inject an external PHP patch script (repeatable)
--build-shared=<list>	-D	Extensions to compile as shared .so / .dll instead of static

micro Options

Option	Description
--with-micro-fake-cli	Make micro's PHP_SAPI report cli instead of micro
--without-micro-ext-test	Disable the post-build extension test for micro.sfx
--with-micro-logo=<path>	Embed a custom .ico icon into micro.sfx (Windows only)
--enable-micro-win32	Build micro.sfx as a Win32 GUI application instead of a console app (Windows only)

frankenphp Options

Option	Description
--enable-zts	Required for FrankenPHP; enables thread-safe mode
--with-frankenphp-app=<path>	Embed a directory into the FrankenPHP binary

embed Options

Option	Description
--build-shared=<list>	Compile specific extensions as shared libraries (requires embed SAPI)

Download Pass-through Options

All downloader options are available with the --dl- prefix:

Option	Description
--dl-with-php=<ver>	PHP version to download (default: 8.4)
--dl-prefer-binary	Prefer pre-built binaries for dependencies
--dl-parallel=<n>	Number of parallel downloads
--dl-retry=<n>	Number of retries on failure
--dl-custom-url=<src:url>	Override a source download URL
--dl-custom-git=<src:branch:url>	Override with a custom git repository

Examples

# Build cli SAPI
spc build:php "bcmath,openssl,curl" --build-cli

# Build cli + micro together
spc build:php "bcmath,phar,openssl,curl" --build-cli --build-micro

# Build with a specific PHP version
spc build:php "bcmath,openssl" --build-cli --dl-with-php=8.3

# Bake INI into the binary
spc build:php "bcmath,pcntl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"

# Keep debug symbols
spc build:php "bcmath,openssl" --build-cli --no-strip

# Build FrankenPHP (ZTS required)
spc build:php "bcmath,openssl,curl" --build-frankenphp --enable-zts

build:php-cli, build:php-fpm, build:php-micro, build:php-embed, build:php-cgi, build:frankenphp

Dedicated single-target build commands. These accept the same options as build:php except the SAPI-selection flags (--build-*), which are implicit.

spc build:php-cli "bcmath,openssl,curl"
spc build:php-micro "bcmath,phar,openssl"
spc build:php-fpm "bcmath,openssl,curl,pdo_mysql"
spc build:php-embed "bcmath,openssl"
spc build:frankenphp "bcmath,openssl,curl" --enable-zts

craft

Read a craft.yml and run the full build pipeline automatically.

spc craft [path/to/craft.yml]

If no path is given, craft.yml in the current working directory is used. See craft.yml configuration for the file format.

doctor

Diagnose whether the current environment can compile PHP normally.

spc doctor [--auto-fix[=never]]

Option	Description
--auto-fix	Automatically fix detected issues using the system package manager
--auto-fix=never	Report issues but never attempt automatic fixes

dev:shell

Enter an interactive shell with StaticPHP's build environment pre-loaded (compiler wrappers, buildroot/, pkgroot/ paths, etc. on PATH).

spc dev:shell

Useful for compiling small programs against libphp.a (embed SAPI) or inspecting the build environment manually.