Skip to content
BOA Documentation

Powered by Grav

Shell & Drush — Cheat Sheet

Shell & Drush — Cheat Sheet

Your account comes with a real command line — a limited shell fenced to your own space, no root and nothing to install. This page is the quick primer: how to get in, run Drush, choose the PHP your tools use, move a site around, and hand a developer their own login. Everything here links to the full story.

The essentials in 30 seconds

  1. Two logins per account — oN only browses files; oN.ftp does all the real work (Drush, Composer, PHP switching). When in doubt, use .ftp. → Drush basics
  2. Three ways in, one account — an SSH shell, SFTP, and (where your host offers it) FTPS, all on the same oN.ftp login. → Shell, SFTP & FTPS
  3. Two Drush families — drush, the system-wide Drush 8, for Drupal 6/7; vdrush, each site's own bundled Drush, for Drupal 8+. → Drush basics
  4. Your CLI PHP is yours — the PHP your Drush and Composer run under is a plain file you set, independent of the version serving the live site. → Drush basics
  5. Extra developer logins — hand out sub-accounts, each fenced to your own sites. → Developer sub-accounts

Open a shell (and move files)

BASH
ssh [email protected]        # port 22

Same account, same credentials, three protocols: the shell above, SFTP for file transfer (host = your server, port 22, user oN.ftp), and — where your host has switched it on — FTPS ("FTP with explicit TLS", port 21). Plain, unencrypted FTP is always refused.

→ Connecting: shell, SFTP & FTPS

Log in without a password

Make a key on your own computer, then install its public half by hand — ssh-copy-id doesn't work through the limited shell:

BASH
ssh-keygen -t ed25519 -C "you@your-computer"
# paste ~/.ssh/id_ed25519.pub into ~/.ssh/authorized_keys (one key per line)

If key logins ever stop working, it's almost always permissions:

BASH
chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys

→ SSH keys, step by step

Run Drush: drush and vdrush

Legacy Drupal 6/7 sites use the system Drush 8, plain drush, with a dotted alias:

BASH
drush @example.com status      # also: cc all · updb · uli
drush aliases                  # list your alias names — never type one from memory

Modern Drupal 8+ sites use each site's own bundled Drush, vdrush, with a hyphenated alias (dots become hyphens, except the one before the final extension: @sub.example.com → @sub-example.com). Run it from the platform's app root — the folder with vendor/ — as oN.ftp, and always name the @alias:

BASH
vdrush @sub-example.com cr      # also: updb · uli
drush11 aliases                 # print modern alias names to copy

First time on a platform, unlock its local Drush once with the Unlock Local Drush task in the Ægir control panel, then run vdrush --version to confirm. A Verify, clone, or upgrade re-locks it — just run the task again.

→ Drush basics · Aliases & contrib commands

Pick your CLI PHP version

The PHP your command-line tools use is independent of the live site's. Set a lasting default:

BASH
echo 8.3 > ~/static/control/cli.info      # picked up within a few minutes

Or flip it instantly for your next command — the filename is the switch, highest version wins:

BASH
touch ~/static/control/php83.info         # drop back with: rm ~/static/control/php83.info

Only the PHP versions your host keeps installed are available; if one you want is missing, open a support request. → Drush basics · the live site's PHP version

Export a site: dump it, or pull it home

One line, no interactive login, straight into a local file:

BASH
ssh [email protected] 'drush @example.com sql-dump' > dump.sql

(Modern site: drush11 and the hyphenated alias.) To pull a whole site down, rsync — and the -L is non-negotiable, because the paths under ~/clients and ~/platforms are symlink farms; without it you drag home a bag of shortcuts:

BASH
rsync -avzuL [email protected]:clients/myclient/example.com ./

→ Exporting your site

Connect a database tool over SSH

Sequel Ace, Workbench, TablePlus and friends reach your database through an SSH tunnel — nothing is exposed to the internet:

  • SSH: host = your server, user oN.ftp, port 22
  • MySQL: host 127.0.0.1, port 3306, with the site's own DB user, password and name

→ The database tunnel

Give a developer their own login

Each extra login is one file under ~/users/. To rotate a developer's password, delete their file — it's rebuilt with a fresh one within about three minutes:

BASH
rm ~/users/o1.acmecorp

That's a full rebuild of their home directory (any SSH key they added is wiped, so they re-add it) — your sites are untouched. → Developer sub-accounts

Fetch private code with a deploy key

Public code clones straight from the shell:

BASH
git clone https://github.com/you/mysite.git mysite

For a private repository that Ægir fetches for you (a makefile build, say), those fetches run as your instance's own system user, not your login — so register its key. The readable copy is:

BASH
~/static/o1.id_ed25519.pub      # add its contents as a read-only deploy key

It's a modern ed25519 key; any old RSA USER.id_rsa.pub deploy key is stale. → Building a platform

The files most people touch

File What it does Default
~/.ssh/authorized_keys Your public key(s) for passwordless login — one per line (empty)
~/static/control/cli.info Lasting default PHP version for Drush & Composer (BOA default)
~/static/control/phpNN.info Instant CLI PHP switch — filename is the switch, highest wins (none)
~/users/<name> One file per extra login — rm it to force a fresh password (auto)

Four files, one shell, three ways in — that's most of the surface you'll ever touch. There's no list of commands to memorise, either: the limited shell allows a curated set and prints it on demand — type ? or help at the prompt. What's in it depends on what your host has enabled (for example scp appears only when Node.js is switched on). → The full command list · quick lookup reference

If something's weird

  • Contrib Drush commands "don't exist," or Drush misbehaves → you're on bare oN, not oN.ftp; core works but contributed commands are deliberately not loaded on the wrong login. Which login, and why.
  • vdrush won't run → you must be at the platform's app root, name the @alias, and have run Unlock Local Drush (it re-locks on every Verify or upgrade). The preconditions.
  • Key logins suddenly refused → check ~/.ssh is 700 and authorized_keys is 600; and remember every account still gets a 90-day password refresh even with a key. Connection problems.

Going deeper

© 2026 BOA Documentation. All rights reserved.