# Ivory

Ivory is a cross-platform CLI tool that manages local PHP runtimes and runs Composer and PHP scripts in a consistent, project-aware way.

It lets you:

• Install and manage multiple PHP versions under ~/.ivory
• Pick a default (global) PHP version and per-project version
• Generate a ivory.json project config
• Run PHP directly via Ivory
• Proxy Composer commands through a known PHP version
• Define reusable “scripts” in ivory.json and run them easily
• Inspect your environment and check what Ivory sees (ivory doctor)

Table of contents

• Features
• Requirements
• Installation
• Configuration (ivory.json)
• Commands
• iv init
• iv install
• iv list
• iv php
• iv run
• iv scripts
• iv use
• iv default
• iv composer
• iv isolate
• iv scaffold:ci
• iv scaffold:docker
• iv completion
• iv doctor
• Data & directories
• License

Features

• Local PHP version management
• Installs PHP builds under ~/.ivory/versions/<platform>/<version>
• Uses a JSON manifest (~/.ivory/php-versions.json) to know where to download PHP from
• iv install 8.3 etc.

• If a command resolves to a non-system PHP version that isn't installed yet, Ivory will install it automatically before running your command.

• Project-aware PHP selection

• Per-project PHP version via .ivory.php-version
• Global default PHP version via ivory default

• Falls back to system php when appropriate

• Project configuration with ivory.json

• php.version, extra INI and CLI args
• Named scripts that describe how to run your app/tools

• Framework presets (Generic, Laravel, Symfony) via ivory init

• Composer integration

• Finds or downloads a composer.phar
• Runs Composer using a specific PHP version

• Can run Composer scripts through your configured PHP toolchain

• Nice DX

  • Uses System.CommandLine for a clean CLI
  • Uses ivory doctor to show what Ivory sees (PHP, Composer, config, etc.)
  • Scaffolds a basic public/index.php that tries to load vendor/autoload.php
  • Optional per-project PHP home (.ivory/php) to keep ini overrides local

Installation

Quick install (prebuilt binaries)

Downloads come from the latest release at https://github.com/rizwan3d/Ivory/releases/latest/download/<platform-archive>.

# Linux (x64)
bash <(curl -fsSL https://raw.githubusercontent.com/rizwan3d/Ivory/refs/heads/master/install/linux.sh)

# macOS (arm64 or x64)
bash <(curl -fsSL https://raw.githubusercontent.com/rizwan3d/Ivory/refs/heads/master/install/mac.sh)

# Windows (PowerShell 5+; AMD64 or ARM64)
powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/rizwan3d/Ivory/refs/heads/master/install/windows.ps1 | iex"

The installers place ivory under a user-scoped bin directory (~/.ivory/bin on Unix, %LOCALAPPDATA%\Ivory\bin on Windows) and add it to PATH.

Uninstall

# Linux/macOS
bash <(curl -fsSL https://raw.githubusercontent.com/rizwan3d/Ivory/refs/heads/master/install/uninstall.sh)

# Windows (PowerShell 5+)
powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/rizwan3d/Ivory/refs/heads/master/install/uninstall.ps1 | iex"

Configuration (ivory.json)

Ivory looks for a ivory.json starting from the current directory and walking up parent directories.

Example ivory.json

{
  "php": {
    "version": "8.3",
    "ini": [
      "memory_limit=512M"
    ],
    "args": [
      "-d", "date.timezone=UTC"
    ]
  },
  "scripts": {
    "serve": {
      "description": "Run PHP built-in server",
      "phpFile": "-S",
      "phpArgs": [
        "localhost:8000",
        "public/index.php"
      ],
      "args": []
    },
    "console": {
      "description": "Run framework console",
      "phpFile": "bin/console",
      "phpArgs": [],
      "args": []
    }
  }
}

Schema (simplified)

• php

• version (string, optional) - preferred PHP version for this project (e.g. "8.3" or "latest").

• ini (array of string) - extra -d INI settings to pass to PHP.

• args (array of string) - extra arguments always passed to PHP.

• scripts (object)

• keys = script names (e.g. "serve", "test", "console").

• values = IvoryScript:

  • description (string, optional) – human-readable description.
  • phpFile (string, required) – the PHP entry file or command (e.g. "public/index.php", "bin/console", "-S").
  • phpArgs (array of string, optional) – arguments placed before the phpFile or used as raw PHP arguments.
  • args (array of string, optional) – additional arguments appended after phpFile / phpArgs.

Internally, these are represented by IvoryConfig and IvoryConfig.IvoryScript in Ivory.Domain.Config.

Commands

iv init

Create a starter ivory.json for the current project and scaffold public/index.php if it doesn’t exist.

iv init [--framework <Generic|Laravel|Symfony>] [--php <version>] [--force]

• --framework – choose a preset (Generic, Laravel, Symfony).
• --php – default PHP version to write into ivory.json.
• --force – overwrite an existing ivory.json.

This uses IPhpVersionResolver, IvoryConfigSerializer and IPublicIndexScaffolder under the hood.

ivory install

Install a PHP runtime for the current platform.

iv install <version>

Examples:

iv install 8.3
iv install 8.2

This calls IPhpInstaller.InstallAsync, which:

• Looks up the version in ~/.ivory/php-versions.json (PhpVersionsManifest).
• Downloads the appropriate artifact.
• Verifies SHA256.
• Extracts it into ~/.ivory/versions/<platform>/<version>.

ivory list / ivory ls

List installed PHP versions:

iv list
# or
iv ls

Uses IPhpInstaller.ListInstalledAsync() and prints out versions in order.

ivory php

Run php through Ivory with a specific PHP version (or project/global default).

iv php [--php <version>] [--] [args...]

Examples:

iv php -- -v
iv php --php 8.3 -- -v
iv php --php 8.3 -- -r "echo 'Hello from Ivory';"

This calls IPhpRuntimeService.RunPhpAsync with null script path and just forwards your arguments.

ivory run

Run a named script from ivory.json or a direct PHP file.

iv run <script-or-file> [--php <version>] [--] [extra-args...]

Behavior:

1. Ivory loads the nearest ivory.json via IProjectConfigProvider.

2. If <script-or-file> matches a script name in scripts, it:

3. Builds the PHP command from php, phpFile, phpArgs, and args.

4. Otherwise, it treats <script-or-file> as a path to a PHP file relative to the current directory.

Examples:

iv run serve
iv run console -- migrate
iv run public/index.php --php 8.3

ivory scripts

List available scripts from ivory.json:

iv scripts

Shows:

• Script name
• Description
• The effective PHP command line that would be executed.

ivory use

Set the project-local PHP version by writing .ivory.php-version in the current directory:

iv use <version>

Example:

iv use 8.3

Ivory will prefer this version when running commands inside this project directory.

ivory default

Set the default / global PHP version (e.g. stored in ~/.ivory/config.json or equivalent):

iv default <version>

Example:

iv default 8.2

Used when there is no .ivory.php-version and no php.version in ivory.json.

ivory composer

Run Composer through Ivory.

iv composer [--php <version>] [--] [args...]

Examples:

iv composer install
iv composer update
iv composer run-script test
iv composer --php 8.3 -- install

Internally, IComposerService:

• Locates composer.json and project root.
• Ensures a composer.phar is available (downloading if needed).
• Uses IPhpRuntimeService to run php composer.phar <args> with the chosen PHP version.

ivory isolate

Create a per-project PHP home in .ivory/php/ with its own php.ini and conf.d/ directory for extension ini files.

iv isolate

After running this once in a project, Ivory will automatically set PHPRC and PHP_INI_SCAN_DIR to use your local php.ini and conf.d/ when executing PHP/Composer through Ivory, keeping settings and extensions from bleeding across projects.

ivory scaffold:ci

Generate CI templates wired to Ivory for GitHub Actions or GitLab CI.

iv scaffold:ci              # GitHub by default
iv scaffold:ci --target gitlab
iv scaffold:ci --target both --force

Creates .github/workflows/ivory-ci.yml and/or .gitlab-ci.yml running dotnet build plus a Ivory doctor + PHP version check.

• Uses the resolved PHP version (project .ivory.php-version → ivory.json php.version → global default); when resolution is system, the workflow pins 8.3 so CI has a concrete PHP tag.
• Pass --force to overwrite existing files.

ivory scaffold:docker

Generate a Dockerfile and docker-compose.yml using the resolved PHP version.

iv scaffold:docker

Produces a simple Dockerfile (php:<version>-cli) and docker-compose.yml exposing port 8000; extend to install needed PHP extensions.</version>

• The PHP tag is taken from the resolved Ivory PHP version; if it would be system, Ivory pins 8.3 for the Docker base image.
• Use --force to overwrite existing Dockerfile / docker-compose.yml.

ivory completion

Generate a shell completion script (bash, zsh, fish, PowerShell) that includes commands, ivory.json script names, and PHP versions/aliases from your manifest.

iv completion bash     # bash
iv completion zsh      # zsh
iv completion fish     # fish
iv completion powershell

Tip: source <(ivory completion bash) or add to your shell init file.

ivory doctor

Inspect environment and show what Ivory sees:

iv doctor

Typical output includes:

• Current platform (PlatformId)
• Home directory and ~/.ivory layout (versions, cache, manifest path)
• Installed PHP versions
• Effective project / global PHP version
• Locations of composer.phar and system composer
• Whether ivory.json was found and where
• Whether per-project isolation is enabled for this directory (and paths to .ivory/php/php.ini and conf.d if present)

This uses:

• IEnvironmentProbe to find system php/composer
• IPhpInstaller to inspect installed versions
• IComposerService to locate Composer
• IProjectConfigProvider to find ivory.json

Data & directories

Ivory stores its own data under:

~/.ivory/
    php-versions.json   # PhpVersionsManifest (download sources & checksums)
    versions/           # Installed PHP runtimes, per platform/version
    cache/php/          # Download cache for PHP archives
    config.json         # Global config (e.g. default PHP version)

Per-project data:

• ivory.json – project configuration (PHP + scripts).
• .ivory.php-version – per-project PHP version pin.