Skip to main content
Version: v2

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, memorable ones, so your development 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 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.

It also ships an example local Ahoy file, .ahoy.local.example.yml. Copy it to .ahoy.local.yml and add your own commands there: Git ignores the copy, and ahoy local <command> runs the commands you put in it. ahoy local --help lists them, not ahoy --help, and 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 before it runs the command, 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, and it runs every command from the directory that holds the file, the project root. You can call Ahoy from any directory in the project. The project root also holds .ahoy.local.yml, .env, and .env.local, and Git ignores .env.local as it does .ahoy.local.yml.

Every command runs through the entrypoint at the bottom of .ahoy.yml. It loads your environment variables and makes sure the drevops/vortex-tooling package is in vendor/. On a fresh clone, the first command installs it, so 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 one in the cli container, prefix it with ahoy cli, the way the shipped ahoy test command does.

The following command has a usage line and runs PHPUnit and ahoy info after you confirm:

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, with its usage line when it has one.

Loading 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. Anything 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

Running CLI commands​

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

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

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_

Your shell's variables here include the ones the entrypoint loaded from .env and .env.local, 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 escape a double quote inside an argument that contains spaces as \".

You can also use shortcuts for common commands:

# Run Drush command
ahoy drush status
# Run Composer command
ahoy 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) and, when PACKAGE_TOKEN is set, registers it as a GitHub token.

Shipped commands​

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

AreaCommandsWhat they do
Projectbuild, info, reset, doctor, update-vortexbuild rebuilds the project from scratch, info shows the project details, reset removes the containers and build files, doctor finds setup problems, and update-vortex updates the project from the template
Containersup, down, start, stop, restart, logs, cliup builds and starts the containers, down removes them with their volumes, start, stop, and restart act on existing containers, logs shows their logs, and cli opens a shell or runs a command in cli
Composer and Drushcomposer, drush, logincomposer and drush run those tools in cli, and login unblocks user 1 and prints a one-time login link
Databasefetch-db, import-db, export-db, provision, reload-db, pull-db, dbfetch-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, and db opens the database in Sequel Ace
Migration databasefetch-db2, reload-db2, db2The same jobs as fetch-db, reload-db, and db, for the second database
Front-end assetsfei, fe, fed, fewfei installs the front-end dependencies, fe builds the theme assets, fed builds them for development, and few watches them and rebuilds on change
Storybookstorybook, storybook-build, storybook-storiesstorybook starts the development server, storybook-build builds the library served at /storybook, and storybook-stories generates the stories
Code qualitylint, lint-be, lint-fe, lint-tests, lint-sdc, lint-fix, lint-be-fix, lint-fe-fixlint runs lint-be, lint-fe, and lint-tests, lint-fix runs lint-be-fix and lint-fe-fix, and lint-sdc validates the components of a provisioned site
Teststest, test-unit, test-kernel, test-functional, test-functional-javascript, test-js, test-bddtest 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 cachesdebug, flush-redisdebug turns on Xdebug, and flush-redis flushes the Valkey cache in the cache service
DeploymentdeployRuns a deployment by hand, after you confirm; deployments usually run in CI
Local commandslocalRuns 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, and 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.