CLI

The Vortex CLI is a single self-contained binary that scaffolds a new project from the template, updates an existing one, reconfigures it, and reports on the local tooling. It ships as a PHAR, so it needs nothing installed beyond PHP.

Download and run

curl -SsL https://www.vortextemplate.com/install > vortex.phar && php vortex.phar

For the step-by-step walkthrough of setting up a new project, see Installation.

Commands

Command	Purpose
install	Install Vortex from a remote or local repository
update	Update an existing project to a template version
configure	Reconfigure an existing project in place, without downloading
doctor	Report which required tools are installed and running
build	Build the site using ahoy build

Run without a command and the CLI resolves by the state of the target directory: an existing Vortex project is reconfigured, anything else gets a fresh install. So php vortex.phar in an empty directory installs, and the same command inside a project reconfigures it.

List every command and option

php vortex.phar list
php vortex.phar install --help

install

Downloads the template, asks the configuration questions, and writes the result into the destination directory.

Option	Short	Description
--destination		Destination directory. Defaults to the current directory
--root		Path used to resolve relative paths. Defaults to the current directory
--uri	-l	Remote or local repository URI, with an optional git ref after #
--no-interaction	-n	Do not ask any interactive question
--config	-c	JSON string, or path to a JSON file, of CLI configuration
--prompts	-p	JSON string, or path to a JSON file, of prompt answers keyed by prompt ID
--schema		Output the prompt schema as JSON and exit
--validate		Validate the supplied answers without installing
--build	-b	Run the build after installing, without prompting
--no-cleanup		Do not remove the CLI after a successful installation
--agent-help		Output instructions for AI agents and exit

The --uri option accepts a git ref after #, which selects what to install:

Choosing what to install

php vortex.phar install --uri=https://github.com/drevops/vortex.git
php vortex.phar install --uri=https://github.com/drevops/vortex.git#stable
php vortex.phar install --uri=https://github.com/drevops/vortex.git#1.2.3

update

Updates an existing project to a template version, re-applying the answers discovered from the project. It takes every install option, plus:

Option	Short	Description
--to		The template version to update to. Defaults to the latest of this major

Updating a project

php vortex.phar update
php vortex.phar update --to=1.2.3
php vortex.phar update --no-interaction --destination=./my-project

An explicit --uri names both the repository and the ref, so it takes precedence over --to. A project of a different major version is refused, with a pointer to the release that can update it.

configure

Reconfigures an existing project in place. Nothing is downloaded: the project is both the source the answers are read from and the tree they are written to.

Option	Short	Description
--destination	-d	Project directory. Defaults to the current directory
--apply	-a	Write the collected answers to the project
--no-interaction	-n	Do not ask any interactive question
--config	-c	JSON string, or path to a JSON file, of CLI configuration
--prompts	-p	JSON string, or path to a JSON file, of prompt answers keyed by prompt ID
--schema		Output the prompt schema as JSON and exit
--validate		Validate the supplied answers without changing anything
--agent-help		Output instructions for AI agents and exit

Without --apply nothing on disk changes: the run collects answers and reports them, which is how you read a project's current configuration. A non-interactive run writes them to stdout as JSON.

Reading and then writing a configuration

php vortex.phar configure --no-interaction > current.json
php vortex.phar configure --apply --prompts=current.json

What configure can change

configure re-runs the same processing an install performs, against the project instead of a freshly downloaded template. Answers whose effect is to remove something - a service, a CI provider's files, the AI agent instructions - take effect. Answers that fill in template placeholders, such as the site name, do not: the placeholders were consumed at install time and are no longer in the project. Use update to bring template changes back in.

doctor

Checks for the tools a Vortex project needs: Docker, Docker Compose, Ahoy and Pygmy. It reports whether each is installed and running, the version of each one present, and how to install the ones that are missing. It only reports - it never changes the project.

Option	Short	Description
--destination	-d	Directory to run the checks in. Defaults to the current directory
--only	-o	Comma-separated subset of requirements to check
--no-summary		Hide the summary listing tool versions

This is the host-level check that runs before a project exists. Once a project is built, ahoy doctor goes further and inspects the running stack itself - ports, containers, the web server and the site bootstrap.

build

Builds the site by running ahoy build in the project directory.

Option	Short	Description
--profile	-p	Build from the install profile instead of a database
--skip-requirements-check		Skip checking for the required tools

Non-interactive use

Every question can be answered up front, which is what makes the CLI usable from a script or a pipeline. Ask for the schema, build an answers object from it, optionally validate, then install:

Discover the available prompts

php vortex.phar install --schema

Validate answers without installing

php vortex.phar install --validate --prompts='{"name":"My Project","hosting_provider":"lagoon"}'

Install non-interactively

php vortex.phar install --no-interaction --prompts=prompts.json --destination=./my-project

--prompts keys are the prompt IDs from --schema. --config is separate: it carries CLI configuration such as the repository and ref, not prompt answers.

--schema, --validate and --agent-help are available on install, update and configure, and answer identically on each: the questions belong to the build, not to a verb. They also answer without a command name, so a freshly downloaded binary can describe its own questions before anything exists on disk:

Describe the questions with nothing installed yet

php vortex.phar --schema

A non-interactive run suppresses the closing guidance - the boxes telling you what to do next. Progress and status output is still reported, so a scripted install remains readable in a log. Only configure reduces its stdout to a single JSON document.

Using an AI agent

--agent-help prints the whole workflow above as instructions written for an AI coding agent:

php vortex.phar --agent-help

Environment variables

Variables are scoped by what they configure. Settings that belong to the CLI itself use the VORTEX_CLI_ prefix; settings that belong to the install command use VORTEX_CLI_INSTALL_.

Variable	Purpose
VORTEX_CLI_VERSION	Override the version stamped into the binary
VORTEX_CLI_URL	Where ahoy update-vortex downloads the PHAR
VORTEX_CLI_PATH	Local PHAR path; overrides the URL
VORTEX_CLI_URL_CACHE_BUST	Cache-busting parameter for the URL
VORTEX_CLI_INSTALL_TMP_DIR	Working directory for the downloaded source
VORTEX_CLI_INSTALL_TEMPLATE_REPO	Template repository to install from
VORTEX_CLI_INSTALL_PROMPT_<ID>	Answer for a single prompt, by prompt ID

Superseded variable names

These variables were previously prefixed with VORTEX_INSTALLER_. The old names still work: when the current name is unset, the matching legacy name supplies the value and the run prints a notice naming its replacement. The fallback exists to ease migration and will be removed in a future major version.

Distribution

The CLI is published to three stable paths, each served with no file extension:

Path	Contents
https://www.vortextemplate.com/install	The current major
https://www.vortextemplate.com/v1/install	The 1.x line
https://www.vortextemplate.com/v2/install	The 2.x line

The bare /install path always serves the current major. Each per-major path is built from that major's own branch, so pinning to /v1/install or /v2/install keeps you on that line.

A build refuses to run against a project from a different major version and points you at the matching path instead, so an accidental cross-major update cannot happen silently.

Updating an existing project

Inside a Vortex project, ahoy update-vortex downloads the CLI and runs it for you - you do not need to fetch the binary yourself. See Updating Vortex.

Maintaining the CLI

For how the CLI is developed, tested and released, see Maintenance / CLI.