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:

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.

Everyday commands

Once you're in your oN.ftp shell, cd into the site you want to work on and run Drush there. Just typing drush runs the system's Drush 8, which is right for most day-to-day work.

Here are the commands you'll reach for most:

# Where am I? Site status, DB connection, Drupal + PHP versions
drush status

# Clear / rebuild the cache after a config or code change
drush cr          # Drupal 8+  (cache rebuild)
drush cc all      # Drupal 6/7 (cache clear)

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

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

A few notes on these:

  • drush uli prints a one-time login URL. Open it in your browser to land logged in as the admin user — handy when you've locked yourself out or just don't want to hunt for the password.
  • drush cr is the Drupal 8+ cache rebuild. On an older Drupal 6 or 7 site use drush cc all instead.
  • drush updb applies any pending database updates a module or core update is waiting on. On a Drupal 8+ site, run it with your site's own bundled Drush — vdrush updb (see the vdrush section below); the system Drush is for legacy Drupal 6/7 sites.

If a command reports it can't find your site, make sure you cd'd into the site's directory first, or point Drush at the site with its alias (for example drush @your-site.example.com status). Your site aliases are set up for you by BOA — see Site aliases & redirects.

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

Drush 8 (drush) handles most sites, but modern Composer-managed Drupal (Drupal 10 and up) ships its own copy of Drush inside the site, under vendor/. To run that bundled Drush, BOA gives you vdrush — a shortcut that points at the site's vendor/drush/drush/drush.php. Use it much like drush, from inside the platform where the site lives:

# cd into the platform's app directory first (where vendor/ lives), then:
vdrush cr
vdrush updb

You can also target a site by its alias with vdrush @alias. One thing to watch: this modern Drush uses a different alias format from drush8. Where drush8 writes the alias with dots (drush @your-site.example.com), the modern Drush replaces the dots with hyphens except the last one (@your-site-example.com). Rather than guess, list your exact alias names with:

drush11 aliases

…and copy the one you want.

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 Aegir 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: 
    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.

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." You're almost certainly connected as oN instead of oN.ftp, or the platform's local Drush is still locked. Reconnect as oN.ftp and run Unlock Local Drush first.
  • "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