Skip to content
BOA Documentation

Powered by Grav

Running Drush

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 and Composer run 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:

Login Use it for
oN Quick file browsing only. Drush here will not behave correctly.
oN.ftp All Drush, vdrush, and Composer work.

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 spell the alias almost — but not quite — the same way:

  • Legacy Drupal 6/7 — the alias is simply your site's address in full dotted form, e.g. @example.com or @sub.example.com. List them with drush8 aliases (or just drush aliases).
  • Modern Drupal 8+ — every dot except the last one becomes a hyphen; the last dot always stays. A bare domain has only that last dot, so its alias is identical in both families: @example.com works with drush and vdrush alike. Only names with more dots change spelling — sub.example.com becomes @sub-example.com, and example.com.au becomes @example-com.au. List the exact names with drush11 aliases and copy the one you want.

(More on the modern spelling 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):

SH
# 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 site's alias instead (below).

Choosing which PHP version Drush and Composer use

Drush and Composer both run on PHP, and you get to choose which PHP version — separately for each of your Octopus instances, and even instantly for a one-off job. One choice covers both tools: the Drush PHP version and the Composer PHP version are the same setting, with nothing separate to configure for either. And it's independent of the PHP version that serves your live site to visitors — changing it here never touches the pages they see. What it does steer is command-line work: the commands you type, and the Drush runs behind your Ægir tasks.

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:

SH
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) — and for the Drush runs behind your Ægir tasks. The change is picked up within a few minutes. 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:

SH
# 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:

SH
rm ~/static/control/php83.info

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

One thing to know before you leave a marker lying around: the instant switch steers your Ægir backend too. From the moment the file exists, the Drush runs behind your Ægir tasks — Verify, Install, Clone, Migrate — use the marked version as well, and keep using it while the marker is there. Use it freely for a one-off job, then remove the marker so everything — backend included — drops back to your cli.info default.

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).

The modern alias spelling differs from drush8's only when the name has more than one dot: every dot except the last one becomes a hyphen, and the last dot always stays. A bare domain is therefore spelled the same in both families — @example.com works with drush8 and vdrush alike — while @your-site.example.com (the drush8 spelling) becomes @your-site-example.com. Never type it from memory — list your exact alias names and copy the one you want:

SH
drush11 aliases    # prints the modern alias names vdrush uses

Then run, for example:

SH
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:
    SH
    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 — 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.
  • "Composer stops with Failed to make the directory containing [web-root]/sites/... writable." Composer was refreshing one of the files Drupal scaffolds under sites/ and could not write there. BOA keeps the sites/ and sites/default/ directories of a codebase you own writable for your shell user, so if you still see this, run the platform Verify task once (it re-applies the permission map) and retry. Unlock Local Drush only unlocks the bundled Drush; it has nothing to do with Composer's access to sites/. And remember the rule from Deploying your code: a platform with live sites on it is treated as frozen, so composer require there is possible but not recommended; build a fresh platform and migrate instead.

© 2026 BOA Documentation. All rights reserved.