Running Drush

Drush is the command-line tool for Drupal. From your own shell you can clear a site's cache, run its database updates, or grab a one-time login link — without clicking through the UI. This page shows the everyday commands, how to pick the PHP version Drush runs under, and how to use a site's own bundled Drush when a modern Drupal site needs it.

First: connect as oN.ftp, not oN

Everything on this page works from your oN.ftp shell — the limited shell BOA gives you for command-line work. Your account has two logins:

The oN.ftp shell is the one wired up to read your PHP-version settings and run Drush the right way. If Drush ever gives you strange errors that look like Drupal or server problems, the usual cause is that you connected as oN instead of oN.ftp. Reconnect as oN.ftp and try again.

See Connecting to your account for how to log in over SSH/SFTP.

Which Drush — it depends on your Drupal version

BOA gives you two Drush tools, and which one you use depends on the site's Drupal version. This matters: using the wrong one just fails with confusing errors.

• Legacy Drupal 6 / 7 → the system Drush 8, which you run as drush.
• Modern Drupal 8 and newer (Drupal 8/9/10/11) → the site's own bundled Drush, which you run as vdrush (see Using a site's own Drush with vdrush below). The system Drush 8 cannot start up a Drupal 8+ site, so drush cr / drush updb will not work on a modern site — you must use vdrush.

Always use your site's alias — never run Drush bare in the site folder

Whichever Drush you use, point it at the site with the site's alias (@…) rather than cd-ing into the site folder and typing a bare drush cr. Running standalone Drush inside the site directory is unsupported in BOA and can clash with the site's own bundled Drush.

The two Drush families use different alias formats:

• Legacy Drupal 6/7 — the alias is simply your site's address in dotted form, e.g. @example.com. List them with drush8 aliases (or just drush aliases).
• Modern Drupal 8+ — the alias is hyphenated (dots replaced with hyphens except the last one before the extension), e.g. @example-com. List the exact names with drush11 aliases and copy the one you want.

(More on the modern format in the vdrush section. drush11 there is only being used to print the alias name — you still run the site with vdrush.)

Everyday commands (legacy Drupal 6 / 7, with drush)

For a legacy Drupal 6/7 site, run the system drush with the dotted alias (your site's address, e.g. @example.com; list them with drush8 aliases):

# Where am I? Site status, DB connection, Drupal + PHP versions
drush @example.com status

# Clear the cache after a config or code change
drush @example.com cc all

# Run pending database updates (e.g. after a module update)
drush @example.com updb

# Get a one-time login link, so you can log in as admin
drush @example.com uli

• drush @site uli prints a one-time login URL — handy when you've locked yourself out.
• drush @site cc all clears the Drupal 6/7 cache. (The Drupal 8+ equivalent is cr, run with vdrush — below.)
• drush @site updb applies any pending database updates.

On a modern Drupal 8+ site, none of these run under drush — use vdrush with the hyphenated alias instead (below).

Choosing which PHP version Drush uses

Drush runs on PHP, and you get to choose which PHP version — separately for each of your Octopus instances, and even instantly for a single session. This is independent of the PHP version that serves your live site to visitors; changing it here only affects command-line work.

You control it with small files in ~/static/control/. There are two ways.

A lasting default: cli.info

Put a single PHP version on one line in cli.info:

echo 8.3 > ~/static/control/cli.info

That becomes your instance's default PHP version for Drush and Composer (and bee, on your Backdrop sites). The change is picked up within a few minutes, or on your next login — whichever comes first. The file must contain just one valid version number on one line, nothing else.

An instant switch: phpNN.info

To change version right away for your next command, create an empty control file named for the version you want. Here the filename is the switch — the file's contents don't matter:

# Use PHP 8.3 for Drush from the very next command
touch ~/static/control/php83.info

If more than one phpNN.info file exists, the highest version wins. So to drop back down to 8.2, remove the higher one:

rm ~/static/control/php83.info

…and the wrapper falls back to the next-highest file that's present (8.2 in this example).

Which version to pick

A good rule of thumb: match the PHP version to the site you're working on.

• For a Drupal 6/7 site with drush8, PHP 7.4 is a safe choice.
• For a modern Drupal 10+ site, use a matching modern version such as 8.3 or 8.4.

Not every version is installed on your host — BOA keeps only the ones in use. If you ask for a version that isn't available and Drush complains, that's a sign the version needs to be enabled on the server, which is something your host does for you. Just open a support request and mention which PHP version you need.

Using a site's own Drush with vdrush

The system Drush 8 (drush) is only for legacy Drupal 6/7. Modern Drupal (Drupal 8 and newer) ships its own copy of Drush inside the site, under vendor/, and that is the one that can actually run a modern site. BOA gives you vdrush to run it — a shortcut that points at the site's vendor/drush/drush/drush.php.

vdrush always needs the site's @alias — it never works without one. So vdrush cr on its own does nothing useful; the command is always vdrush @alias <command>. And you must run it from the platform's app root (the folder that contains vendor/), as oN.ftp, after unlocking the site's local Drush (next section).

vdrush uses a different alias format from drush8: where drush8 writes the alias with dots (@your-site.example.com), the modern alias replaces the dots with hyphens except the last one before the domain extension (@your-site-example.com). Never type it from memory — list your exact alias names and copy the one you want:

drush11 aliases    # prints the hyphenated aliases vdrush uses

Then run, for example:

vdrush @your-site-example.com cr      # rebuild the cache (Drupal 8+)
vdrush @your-site-example.com updbst  # preview pending DB updates (makes no changes)
vdrush @your-site-example.com updb    # run pending database updates
vdrush @your-site-example.com uli     # one-time admin login link

drush10 and drush11 are for reading alias names, not for running sites. BOA keeps them standalone only so you can print your modern alias names (drush11 aliases); their dependencies clash unpredictably with the site's own codebase, so always drive a modern Drupal site through vdrush — add Drush to the codebase with Composer if it isn't there already. Drush 12 and newer can't be run standalone at all.

Unlock it first: the "Unlock Local Drush" task

To keep platforms tidy and safe, BOA normally locks that bundled Drush so it isn't run by accident. Before vdrush will work, you unlock it from the UI:

1. In the Ægir Hostmaster UI, open the Platform the site lives on.
2. Run the Unlock Local Drush task on that platform.
3. Connect (or reconnect) to your oN.ftp shell.
4. cd into the platform's app directory (where the vendor/ folder is).
5. Confirm it works:
   SHCopy

   vdrush --version
   

6. Now run your vdrush commands as above.

When you're finished, run the Lock Local Drush task on the same platform to lock it back up. That task is a lighter, targeted alternative to a full Platform Verify — either one re-locks the bundled Drush and restores Drush 8 compatibility. Both are safe to re-run: locking an already-locked platform, or unlocking an already-unlocked one, simply does nothing.

One thing to remember: whenever your platform is re-verified — which happens on its own after most upgrades — the bundled Drush gets locked again. If vdrush suddenly stops working after an upgrade, just run Unlock Local Drush once more and carry on.

If you don't see the Platform tasks you expect in the UI, or a platform won't unlock, that's something your host can look into — open a support request.

Quick troubleshooting

• "vdrush gives me errors / does nothing." The three usual causes: you ran it without the @alias (vdrush always needs one — vdrush @your-site-example.com cr, never bare vdrush cr); you're connected as oN instead of oN.ftp; or the platform's local Drush is still locked. Reconnect as oN.ftp, run Unlock Local Drush, cd to the platform app root, and include the alias.
• "My PHP version won't change." If you used cli.info, give it a few minutes or log in again — it isn't instant. For an immediate change use a phpNN.info file instead.
• "Drush works but Composer doesn't" (or vice-versa) — same cause, same fix: check you're in the oN.ftp shell and that no BOA upgrade is running.

Related

• Connecting to your account — how to log in as oN.ftp over SSH/SFTP.
• Your sites & platforms — where platforms and site aliases come from.
• Site aliases & redirects — the @your-site aliases BOA sets up for Drush.