Drush aliases and contributed commands

Every site in your account already has a short name you can point Drush at — its alias. Instead of remembering where a site's code lives, which database it uses, or which PHP version to run, you just type the alias and Drush figures out the rest. drush @mysite cr clears that site's cache; vdrush @mysite updb runs its database updates. This page shows you how to find your aliases, how to use them, and what to do when a contributed command your site provides suddenly "isn't recognised".

Everything here runs from your own shell. Connect as your oN.ftp user first — that's the login with the BOA shell that makes drush, vdrush and your aliases work. If any command-line tool behaves oddly, the wrong login is almost always the reason. See Your shell and SFTP.

What an alias is

An alias is just a name for one of your sites, written with an @ in front. When you run a Drush command against an alias, Drush looks up that name and already knows:

  • where the site's code lives,
  • which database the site uses,
  • which PHP version to run the command with.

So you never have to cd into the right folder or type any paths. You point at the site by name and run the command. Your host generates these aliases for you automatically and refreshes them whenever a site is verified or changed — you don't create or edit them yourself.

Listing your aliases

To see the aliases available to you, ask Drush for the list:

drush aliases

That prints the aliases in the classic Drush 8 style. If you're working with a newer Drupal site and want the modern (Drush 10+) alias names, use:

drush11 aliases

Each line is an @name you can pass as the first argument to any Drush command.

One small naming quirk

The same site has a slightly different alias name depending on which Drush you ask:

  • Drush 8 keeps the dots: @sub.example.com
  • Drush 10+ turns the dots into hyphens, except the one before the final extension: @sub-example.com

That's it — same site, two spellings. Listing with drush aliases versus drush11 aliases shows you each form, so you can copy the exact name you need.

Using an alias

Once you have the name, put it right after drush (or vdrush) and add the command:

# Clear a site's cache
drush @mysite cr

# Check a site's status
drush @mysite status

# Run database updates after a module or core update
vdrush @mysite updb

# Open a SQL prompt straight into the site's database
drush @mysite sqlc

vdrush is the site's own copy of Drush (handy when a site needs a newer Drush than the system one). It takes the exact same @alias names, so anything you'd write as drush @mysite … works as vdrush @mysite … too. For when to reach for vdrush versus plain drush, see Running Drush.

Tip. If you like, you can also run a command from inside the site's folder without the alias — but pointing at the alias from anywhere is the tidier habit, and it's the way that always picks the right site, code path and PHP version for you.

Your site's own (contributed) Drush commands

Some Drupal modules ship their own Drush commands — CiviCRM adds civicrm commands, Elysia Cron adds its own, and so on. When those modules are part of your site's codebase, their commands load normally in your oN.ftp shell. You just run them against the site's alias like any other command:

drush @mysite civicrm-...      # example: a command CiviCRM provides

There's nothing to switch on. If the module is in your code, its command is available to you from your shell.

"That command isn't recognised" — the usual fix

Here's the one gotcha worth knowing, because the symptom is confusing.

Suppose a plain, built-in command works fine:

drush @mysite cc all     # works — cache clear

…but a command that comes from one of your modules is rejected as not recognised:

drush @mysite elysia-cron run somecron     # "command not found" / not recognised

Nine times out of ten this means you're logged in as the wrong user. If you connected as the plain oN account instead of oN.ftp, your site's contributed commands are deliberately not loaded for that login.

The fix is simply to reconnect:

  1. Disconnect from the oN shell.
  2. Connect again as your oN.ftp user.
  3. Re-run the command — the contributed command loads and works.

Core Drush commands keep working under the plain oN login, which is exactly what makes this puzzling: cache-clear runs, but your module's command doesn't. Matching the two clues — core works, contributed doesn't — points straight at the login. Reconnecting as oN.ftp is all it takes.

If you've confirmed you're on oN.ftp and a contributed command still won't load — or you need one of these commands to run inside an automated background task rather than from your own shell — that part is switched on by your host. Open a support request and ask them to enable it for your instance.

Where to go next