PHP Command Line (CLI): Run PHP Scripts from Terminal

PHP spends most of its working life behind a web server, but it is perfectly happy without a browser. In fact, some PHP tasks are easier to run from a terminal because there is no HTTP request, HTML output, or web server involved.

PHP’s Command Line Interface (CLI) lets you run PHP files directly from a terminal or command prompt. It is useful for maintenance scripts, scheduled jobs, data imports, queue workers, development utilities, and other tasks that should run outside a web request.

If PHP is already installed on your computer or server, you may already have everything you need. The first step is simply to check.

Quick answer: How to run PHP from the command line

Open a terminal, move to the directory containing your PHP file, and run:

php script.php

You can also execute a short piece of PHP without creating a file. The examples below use PHP_EOL for command-line line breaks.

php -r 'echo PHP_VERSION . PHP_EOL;'

The first command runs a PHP file. The second uses the -r option to run PHP code supplied directly on the command line.

Check that PHP CLI is available

Start by checking the PHP version:

php -v

A working installation returns output similar to this:

PHP 8.4.x (cli)
Copyright (c) The PHP Group
Zend Engine v4.4.x

The important part here is (cli). It confirms that the command is using PHP’s Command Line Interface.

If the terminal reports that php is not found or is not recognized, PHP may not be installed or its executable directory may not be in your system’s PATH.

You can also check which PHP executable is being used.

On Linux and macOS:

which php

On Windows Command Prompt:

where php

This is especially useful when a machine has multiple PHP versions installed. The PHP version used by your terminal is not necessarily the same one used by Apache, Nginx, XAMPP, or another web server.

Run a PHP file from the command line

Create a file named colors.php:

<?php

$colors = [
    'Red',
    'Green',
    'Blue',
];

foreach ($colors as $color) {
    echo $color . PHP_EOL;
}

Run it from the directory containing the file:

php colors.php

The output is:

Red
Green
Blue

You may also use the -f option:

php -f colors.php

Both commands execute the same file. The -f option is valid, but it is normally unnecessary. For everyday CLI work, php colors.php is simpler.

Run PHP code without creating a file

For a small test, creating a PHP file can be more work than the code itself. The -r option lets you execute PHP code directly from the command line.

php -r 'echo "Hello from PHP" . PHP_EOL;'

The code passed to -r should not include the opening <?php tag.

This is useful for quick checks such as inspecting the PHP version:

php -r 'echo PHP_VERSION . PHP_EOL;'

Or checking whether an extension is loaded:

php -r 'var_dump(extension_loaded("mysqli"));'

Shell quoting differs between operating systems and shells, so longer code quickly becomes awkward. Once a command starts collecting quotes, variables, and several statements, putting the code in a PHP file is usually the cleaner option.

Pass command-line arguments to a PHP script

PHP provides command-line arguments through two predefined variables: $argc and $argv.

• $argc contains the number of command-line arguments, including the script name.
• $argv contains the arguments as an indexed array.

Create a file named greet.php:

<?php

$name = $argv[1] ?? 'Developer';

echo "Hello, {$name}!" . PHP_EOL;

Run it with an argument:

php greet.php Vincy

The output is:

Hello, Vincy!

In this example, $argv[0] contains the script name and $argv[1] contains Vincy.

You can inspect the complete argument array with:

<?php

print_r($argv);

Running:

php script.php import users.csv

produces an array similar to:

Array
(
    [0] => script.php
    [1] => import
    [2] => users.csv
)

Validate arguments before using them

A CLI script should not assume that every expected argument was supplied. Validate the input before using it, especially when the script changes files or database records.

<?php

if ($argc < 2) {
    fwrite(STDERR, "Usage: php report.php <filename>" . PHP_EOL);
    exit(1);
}

$filename = $argv[1];

echo "Processing: {$filename}" . PHP_EOL;

STDERR is used for the error message, while exit(1) returns a non-zero exit status. That matters when the script is called from a shell script, cron job, deployment process, or another program that needs to know whether execution succeeded.

Read input from the terminal

A CLI script can also ask the user for input while it is running. The simplest approach is to read from STDIN.

<?php

echo "Enter your name: ";

$name = trim(fgets(STDIN));

echo "Hello, {$name}!" . PHP_EOL;

When you run the script, PHP waits for input:

Enter your name: Joe
Hello, Joe!

This works well for small administrative tools and one-off scripts. For automated jobs, command-line arguments or environment variables are usually better because they do not require interactive input.

Useful PHP CLI options

The PHP CLI executable has several command-line options that are useful during development and troubleshooting. You do not need to memorize all of them. A small set covers most day-to-day work.

Show the PHP version

php -v

This shows the PHP CLI version currently used by your terminal.

List installed PHP modules

php -m

This is a quick way to check whether extensions such as mysqli, curl, or mbstring are available to CLI PHP.

Show PHP configuration information

php -i

The output is similar to the information provided by phpinfo(), but printed in the terminal.

If you only need to know which configuration file CLI PHP loaded, use:

php --ini

This is useful when a script behaves differently in the terminal and in a browser. The two environments may load different php.ini files or different extension settings.

Check a PHP file for syntax errors

php -l script.php

If the file is valid, PHP returns:

No syntax errors detected in script.php

This checks syntax only. It does not run the script.

PHP CLI and PHP running through a web server are different environments

The same PHP code can behave differently from the command line and through Apache or Nginx. This is one of the first things to check when a script works in the browser but fails in the terminal, or the other way around.

Common differences include:

• A different PHP version may be used.
• A different php.ini file may be loaded.
• Different PHP extensions may be enabled.
• The current working directory may be different.
• Web-specific values in $_SERVER may be missing.
• CLI scripts are not normally limited by the same PHP execution time limit behavior as web requests.

You can confirm the current PHP binary and configuration with:

php -v
php --ini

If an extension appears to work in the browser but not from the command line, check the CLI module list:

php -m

Do not rely on the current working directory

Relative paths are a common source of CLI bugs. A script may be started from a different directory than the one containing the PHP file.

For example, this path depends on the current working directory:

<?php

$config = require 'config.php';

A safer approach is to build the path from the script’s directory:

<?php

$config = require __DIR__ . '/config.php';

This is especially important for cron jobs and scheduled tasks, where the working directory may not be what you expect.

Use exit codes to report success or failure

A command-line program should tell the calling process whether it completed successfully. PHP’s exit() status code uses 0 to indicate success, while another value indicates an error.

<?php

$filename = $argv[1] ?? null;

if ($filename === null) {
    fwrite(STDERR, "Missing filename." . PHP_EOL);
    exit(1);
}

if (!is_file($filename)) {
    fwrite(STDERR, "File not found: {$filename}" . PHP_EOL);
    exit(2);
}

echo "File found: {$filename}" . PHP_EOL;
exit(0);

This becomes valuable when PHP scripts are used in cron jobs, shell scripts, CI pipelines, or deployment tools. Printing an error message helps a human. Returning the correct exit code helps another program.

Common PHP CLI errors and fixes

“php: command not found” or “php is not recognized”

This usually means PHP is not installed or its executable directory is not available in your system’s PATH.

First, locate the PHP executable. Once you know where it is installed, either run it with the full path or add that directory to PATH.

For example:

/usr/local/bin/php script.php

On Windows, the full path may look similar to:

C:\php\php.exe script.php

The CLI PHP version is different from the browser version

This is common on development machines and servers with multiple PHP versions installed.

Check the CLI version:

php -v

Then check which executable is being used:

which php

On Windows:

where php

If the wrong executable appears first, update your PATH or call the required PHP binary explicitly.

An extension works in the browser but not in CLI

The CLI may load a different php.ini file.

php --ini
php -m

Use these commands to check the configuration file and installed modules used by CLI PHP.

A relative file path stops working

The script may be running from a different working directory. Use __DIR__ for files that live relative to the PHP script.

<?php

$path = __DIR__ . '/data/report.csv';

This is much more reliable than assuming the command was started from the script directory.

The command works manually but fails in cron

Cron normally runs with a smaller environment than your interactive shell. The PHP executable may not be in its PATH, and the working directory may be different.

Use absolute paths for both PHP and the script:

/usr/bin/php /var/www/example/scripts/report.php

Also use absolute paths inside the PHP script when reading or writing files.

Practical uses for PHP CLI

PHP CLI is most useful for work that does not belong inside an HTTP request. Typical examples include:

• Importing or exporting large data files.
• Running scheduled maintenance tasks.
• Processing queued jobs.
• Generating reports.
• Cleaning temporary files or old database records.
• Running deployment or development utilities.
• Testing small pieces of PHP code.

For long-running or resource-heavy jobs, CLI is often a better fit than triggering the same work through a browser. It also makes scripts easier to automate and easier to combine with normal operating-system tools.

PHP CLI command reference

These are the commands used most often in everyday PHP CLI work:

php script.php
php -f script.php
php -r 'echo PHP_VERSION . PHP_EOL;'
php -v
php -m
php -i
php --ini
php -l script.php

For the complete list of options available in your installed PHP version, run:

php --help

PHP CLI is simple once the environment is configured correctly. In practice, the most important habits are knowing which PHP binary is running, checking the CLI configuration separately from the web server, validating arguments, and using reliable file paths.