Ahoy

The Ahoy project describes the tool as follows:

Automate and organize your workflows, no matter what technology you use.

Ahoy is command line tool that gives each of your projects their own CLI app with zero code and dependencies.

Ahoy wraps longer commands into short ones, so your workflow stays the same across projects and team members. This page is for developers who run those commands every day. It shows how to call them and add your own, and explains how Ahoy hands environment variables to the containers.

Vortex comes with a pre-configured .ahoy.yml that wraps the most common development tasks. Shipped commands lists every command it defines.

Vortex also ships an example local Ahoy file, .ahoy.local.example.yml. To add commands for your machine only, copy it to .ahoy.local.yml and add them there. The shipped .gitignore excludes the copy. Run a local command with ahoy local COMMAND, and list the local commands with ahoy local --help. The local command exists only while .ahoy.local.yml does.

Usage

Ahoy commands take these forms:

# Run a command in the global Ahoy file.
ahoy COMMAND [ARGUMENTS] [OPTIONS]

# Run a command in the local Ahoy file.
ahoy local COMMAND [ARGUMENTS] [OPTIONS]

# Show all available commands.
ahoy --help

Everything after the command name reaches the command, flags included. A -- right after the command name is optional: Ahoy removes it, so ahoy test-bdd -- --tags=@smoke passes --tags=@smoke to Behat. Ahoy's own flags, such as --help, --version and --file, go before the command name.

Ahoy looks for .ahoy.yml in the current directory and its parents. It runs every command from the project root, the directory that holds the file. You can call Ahoy from any directory in the project. .ahoy.local.yml, .env and .env.local live in the project root too.

Every command runs through the entrypoint at the bottom of .ahoy.yml. The entrypoint loads your environment variables. It also installs the drevops/vortex-tooling package into vendor/ when it's missing. On a fresh clone, host-side commands such as ahoy doctor and ahoy fetch-db work before you've run composer install.

Configuration

For every key a command can use, see the YAML schema in the Ahoy documentation.

To add a command that passes its arguments through, add an entry under commands in .ahoy.yml:

commands:
  custom:
    cmd: vendor/bin/phpunit --group="smoke" "$@"

Ahoy runs commands on your host. To run a command in the cli container, prefix it with ahoy cli, the way the shipped ahoy test command does.

The following command has a usage line. After you confirm, it runs PHPUnit and then ahoy info:

commands:
  custom:
    usage: Custom action
    cmd: |
      ahoy confirm "Are you sure?" &&
      vendor/bin/phpunit --group="smoke" "$@" &&
      ahoy info

Each command runs under bash -e, so a multi-line command stops at the first line that fails. ahoy confirm is a hidden helper in the shipped .ahoy.yml: it asks the question and carries on only when you answer y or true.

To answer every prompt in advance, set AHOY_CONFIRM_RESPONSE=y, for example in .env.local. Ahoy then prints each prompt with that answer and waits 3 seconds, so you can still press Ctrl+C. To skip the wait, also set AHOY_CONFIRM_WAIT_SKIP=1. Any non-empty value counts as a yes, so AHOY_CONFIRM_RESPONSE=n cancels nothing.

Confirm that Ahoy picked up a new command: ahoy --help lists it next to its usage text.

Environment variables

The entrypoint loads .env and then .env.local, and exports every variable they define, so a value in .env.local overrides the one in .env. A variable already exported in your shell wins over both files, so VORTEX_DEBUG=1 ahoy provision turns on debug output whatever the files say.

➡️ See Variables

Run commands in the CLI container

ahoy cli runs a command in the cli container, where PHP, Composer and Drush live. Without arguments, it opens an interactive shell there:

Ahoy

# Run a command in the CLI container
ahoy cli echo "Hello, World!"
# SSH into the CLI container
ahoy cli

Docker Compose

# Run a command in the CLI container
docker compose exec cli echo "Hello, World!"
# SSH into the CLI container
docker compose exec cli bash

ahoy cli forwards only these variables from your shell into the container:

• TERM and LOCALDEV_URL
• Any variable whose name starts with COMPOSE_, GITHUB_, PACKAGE_, DOCKER_, DRUPAL_, VORTEX_ or ENVIRONMENT_

The entrypoint exports .env and .env.local into your shell first, so a DRUPAL_ or VORTEX_ value in .env.local reaches the command without recreating the container.

ahoy cli joins its arguments into a single bash -c string, so in an argument that contains spaces, escape each double quote as \".

The following shortcuts run Drush and Composer in the cli container:

Ahoy

# Run Drush command
ahoy drush status
# Run Composer command
ahoy composer install

Docker Compose

# Run Drush command
docker compose exec cli drush status
# Run Composer command
docker compose exec cli composer install

The shortcuts add a little on top of the plain commands:

• ahoy drush passes -l ${LOCALDEV_URL}, so the links Drush prints point at your local site.
• ahoy composer lifts Composer's memory limit (COMPOSER_MEMORY_LIMIT=-1). When PACKAGE_TOKEN is set, it registers the token as a GitHub token.

Shipped commands

The following table groups the commands that the shipped .ahoy.yml defines:

Area	Commands	What they do
Project	build, info, reset, doctor, update-vortex	build rebuilds the project from scratch. info shows the project details. reset removes the containers and build files. doctor finds setup problems. update-vortex updates the project from the template.
Containers	up, down, start, stop, restart, logs, cli	up builds and starts the containers. down removes them with their volumes. start, stop and restart act on existing containers. logs shows their logs. cli opens a shell or runs a command in cli.
Composer and Drush	composer, drush, login	composer and drush run those tools in cli. login unblocks user 1 and prints a one-time login link.
Database	fetch-db, import-db, export-db, provision, reload-db, pull-db, db	fetch-db fetches the dump. import-db imports it. export-db exports a dump or image. provision provisions the site. reload-db rebuilds the database container. pull-db downloads the database image. db opens the database in Sequel Ace.
Migration database	fetch-db2, reload-db2, db2	The same jobs as fetch-db, reload-db and db, for the second database.
Front-end assets	fei, fe, fed, few	fei installs the front-end dependencies. fe builds the theme assets. fed builds them for development. few watches them and rebuilds on change.
Storybook	storybook, storybook-build, storybook-stories	storybook starts the development server. storybook-build builds the library served at /storybook. storybook-stories generates the stories.
Code quality	lint, lint-be, lint-fe, lint-tests, lint-sdc, lint-fix, lint-be-fix, lint-fe-fix	lint runs lint-be, lint-fe and lint-tests. lint-fix runs lint-be-fix and lint-fe-fix. lint-sdc validates the components of a provisioned site.
Tests	test, test-unit, test-kernel, test-functional, test-functional-javascript, test-js, test-bdd	test runs every PHPUnit suite. test-unit, test-kernel, test-functional and test-functional-javascript run 1 suite each. test-js runs Jest, and test-bdd runs Behat. Every command except test-js passes extra arguments to its test runner, as in ahoy test -- --filter=testMethodName.
Debugging and caches	debug, flush-redis	debug turns on Xdebug. flush-redis flushes the Redis cache.
Deployment	deploy	Runs a deployment by hand, after you confirm. Deployments usually run in CI.
Local commands	local	Runs the commands in .ahoy.local.yml.

The installer leaves out the commands for features and tools you didn't select, such as flush-redis without Redis or test-bdd without Behat. ahoy --help lists the commands your project has. ahoy help followed by a command name, such as ahoy help few, prints that command's usage line. Many commands also have aliases, such as ahoy rebuild for ahoy build or ahoy ssh for ahoy cli.