Jump to content
Jump to navigation
GitHub

Jump to heading Available commands

Jump to heading list

phab list

This command will list all available commands. You can get specific help for a command with the next command:

Jump to heading help

phab help:<command>

Will display all available arguments and options for that given <command> and some explanatory text.

Jump to heading list:hosts

phab list:hosts
phab list:hosts -v

This command will list all your hosts defined in your hosts-section of your fabfile.yaml. If you increase verbosity via -v phab will output the descriptions and list of public urls for every found configuration.

Jump to heading list:blueprints

Phab list:blueprints

This command will list all found blueprint configurations.

Jump to heading about

phab --config=<your-config> about
phab --config=<your-config> about -v

will display the configuration of host <your-config> and the corresponding dockerHost-config, if any. If you increase the verbosity about will also show from where the values are consumed.

Jump to heading find:property

phab --config=<your-config> find:property

Provides an interactive way to search for a specific property whithout knowing its exact name or location. Just type parts of the property after the prompt, phab will try to autocomplete your input. If the autocomplete does not reveal what you are looking for, just hit enter, phab will show a list of possible candidates, from which you can choose one.

You can limit the search to the current (docker-)host-configuration by prefixing your input with host. or dockerHost..

Phab will output the current value of the searched property and from which resource it was inherited. Please note, if your searched property is a branch (means it has child values) then the inheritance source does only reflect the source of the property itself, not necessarily for its enclosed children.

Jump to heading output

phab --config=<your-config> --blueprint=<your-blueprint-config> output

This command will print the computed configuration from a blueprint as yams. You can copy it and paste it back to the fabfile to make it permanent.

Jump to heading get:property

phab --config=<your-config> get:property <name-of-property>
phab --config=<your-config> get:property <name-of-property> --format json
phab --config=<your-config> get:property <name-of-property> --format yaml

This will print the property-value to the console. Suitable if you want to use phabalicious from within other scripts. You can use the format-option to get the results formatted in a specific way so its easier to reuse and parse the values.

Examples

  • phab --config=mbb get:property host will print the hostname of configuration mbb.
  • phab -cmbb get:property docker.service will print the service of the docker-configuration of mbb.

Jump to heading version

phab --config=<your-config> version

This command will display the installed version of the code on the installation <your-config>.

Available methods:

  • git. The command will get the installed version via git describe, so if you tag your source properly (.e.g. by using git flow), you'll get a nice version-number.

Jump to heading shell

phab --config=<your-config> shell

Will open an interactive shell with your-config. It will utilize all necessary steps to connect to the remote or local instance and provide a shell.

Jump to heading deploy

phab --config=<your-config> deploy
phab --config=<your-config> deploy <branch-to-deploy>
phab --config=<your-config> deploy --arguments <optional-arguments>

This command will deploy the latest code to the given installation.

Behavior:

  • If <branch-to-deploy> is specified, it will deploy that specific branch (overriding the branch configured in the host config)
  • If the host configuration has backupBeforeDeploy set to true, a database backup will be created before deployment starts
  • After a successful deployment, the reset-command will be run
  • Optional arguments can be passed to the deployment process using the --arguments (or -a) option

Arguments:

  • <branch-to-deploy> (optional) - Specific branch to deploy, if not set the branch from host-config is used

Options:

  • --arguments / -a - Pass optional arguments to the deployment process

Available methods:

  • git will deploy to the latest commit for the given branch defined in the host-configuration. Submodules will be synced, and updated.
  • platform will push the current branch to the platform remote, which will start the deployment-process on platform.sh
  • artifacts--ftpc will create a copy of the app in a temporary folder and syncs this folder with the help of lftp with a remote ftp-server.
  • artifacts--git will create a copy of the app in a temporary folder and push it to another git-repository

Examples:

  • phab --config=mbb deploy will deploy the app via the config found in mob
  • phab --config=mbb deploy feature/some-feature will deploy the branch feature/some-feature regardless the setting in the fabfile.

Jump to heading reset

phab config=<your-config> reset

This command will reset your installation

Available methods:

  • composer will run composer install to update any dependencies before doing the reset
  • drush will
    • set the site-uuid from fabfile.yaml (drupal 8)
    • enable a deployment-module if any stated in the fabfile.yaml
    • enable modules listed in file modules_enabled.txt
    • disable modules listed in file modules_disabled.txt
    • revert features (drupal 7) if revertFeatures is true / import the configuration (drupal 8),
    • run update-hooks
    • and does a cache-clear.
    • if your host-type is dev the password gets reset to admin/admin

Examples:

  • phab --config=mbb reset will reset the installation and will not reset the password.

Jump to heading install

phab --config=<your-config> install
phab --config=<your-config> install --skip-reset
phab --config=<your-config> install --force

This command will install a new instance on an existing code-base. It runs all tasks necessary to install the application (e.g., installing a database, setting up configuration).

Behavior:

  • The configuration must have supportsInstalls not set to false (configurations can explicitly disallow installs)
  • Prompts for confirmation before installing (unless --force is used)
  • After installation, runs the reset task (unless --skip-reset is specified)

Options:

  • --skip-reset - Skip running the reset task after installation
  • --force - Skip confirmation prompt

Available methods:

  • drush - for Drupal installations

Configuration:

You can add an installOptions section to your fabfile.yaml. For Drupal installations:

installOptions:
  distribution: thunder
  locale: es

Examples:

  • phab --config=mbb install will install a new instance (with confirmation prompt)
  • phab --config=mbb install --force will install without confirmation
  • phab --config=mbb install --skip-reset will install and skip the reset task afterwards

Jump to heading install:from

phab --config=<your-config> install:from <source-config> <what>

This command will install a new installation (see the install-command) and afterwards will do a copyFrom. The reset-command after the install-command will be skipped and executed after the copyFrom-command. You can limit, what should be copied from: db or files. If <what> is omitted, then everything is copied from.

See also:

  • install
  • install:from-sql-file
  • copyFrom

Jump to heading install:from-sql-file

phab --config=<your-config> install:from-sql-file <sql-file-path>
phab --config=<your-config> install:from-sql-file <sql-file-path> --skip-drop-db

This command will install an application from a local sql-file, by running the three standalone commands install, restore:from-sql-file and reset. It will skip any configuration-import while running install to speed things up.

Passing the option --skip-drop-db will keep the existing DB intact, but this might result in problems while importing the SQL-file, so use with care.

See also:

  • install
  • install:from

Jump to heading backup

phab --config=<your-config> backup <what>

This command will backup your files and database into the specified backup-directory. The file-names will include configuration-name, a timestamp and the git-SHA1. Every backup can be referenced by its filename (w/o extension) or, when git is abailable via the git-commit-hash.

If <what> is omitted, files and db gets backupped, you can limit this by providing db and/ or files.

Available methods:

  • git will prepend the file-names with a hash of the current revision.
  • files will tar all files in the filesFolder and save it into the backupFolder
  • drush will dump the databases and save it to the backupFolder
  • restic will backup the files into a restic repository instead. See offsite backups for more infos.

Configuration:

  • your host-configuration will need a backupFolder and a filesFolder

Examples

  • phab -cmbb backup will backup everything
  • phab -cmbb backup files will backup only public and private files.
  • phab -cmbb backup db will backup the database only.

Jump to heading list:backups

phab --config=<your-config> list:backups

This command will print all available backups to the console.

Available methods

  • restic the restic implementation will filter the list of snapshots by configuration and project name.

Jump to heading restore

phab --config=<your-config> restore <commit-hash|file-name>

This will restore a backup-set. A backup-set consists typically of a database-dump and a gzipped file-archive. You can a list of candidates via phab --config=<config> list:backups

Available methods

  • git git will checkout the given hash encoded in the filename.
  • files all files will be restored. An existing files-folder will be renamed for safety reasons.
  • mysql, sqlite will import the database-dump.
  • restic will restore the files and saved db dumps (You might need to run another restore to restore a sql-dump)

Jump to heading get:backup

phab --config:<config> get:backup <commit-hash|file-name>

This command will copy a remote backup-set to your local computer into the current working-directory.

See also:

  • restore
  • backup

Jump to heading copy-from

phab --config=<dest-config> copy-from <source-config>
phab --config=<dest-config> copy-from <source-config> <what>
phab --config=<dest-config> copy-from <source-config> <what> --skip-reset
phab --config=<dest-config> copy-from <source-config> <what> --skip-drop-db

This command will copy database and/or files from source-config to dest-config. The source configuration must have supportsCopyFrom set to true.

Behavior:

  • If <what> is omitted, both database and files will be copied (default: db and files)
  • Files are copied via rsync from source to destination
  • Database is dumped from source and restored to destination
  • After copying the database, the reset-command gets executed (unless --skip-reset is specified)
  • By default, the destination database is dropped before import (unless --skip-drop-db is specified)

This is the ideal command to copy a complete installation from one host to another.

Arguments:

  • <source-config> (required) - The configuration to copy from
  • <what> (optional) - What to copy: db and/or files. If omitted, both are copied.

Options:

  • --skip-reset - Skip running the reset task after importing the database
  • --skip-drop-db - Skip dropping the destination database before importing

Available methods

  • ssh will create all necessary tunnels to access the hosts.
  • files will rsync all new and changed files from source to dest
  • mysql, sqlite will dump the database and restore it on the dest-host.

Examples

  • phab -cmbb copy-from remote-host will copy db and files from remote-host to mbb
  • phab -cmbb copy-from remote-host db will copy only the db from remote-host to mbb
  • phab -cmbb copy-from remote-host db --skip-reset --skip-drop-db will copy only the db from remote-host to mbb, without dropping the db and without running the reset task afterwards.
  • phab -cmbb copy-from remote-host files will copy only the files from remote-host to mbb

Jump to heading drush

phab --config=<config> drush "<drush-command>"

This command will execute the drush-command on the remote host specified in <config>. Please note, that you'll have to quote the drush-command when it contains spaces.

Available methods

  • Only available for the drush-method

Examples

  • phab --config=staging drush "cc all -y"
  • phab --config=local drush fra

Jump to heading drupal

phab --config=<config> drupal "<drupal-command>"

This command will execute a drupal-console command on the remote host. Please note, that you'll have to quote the command when it contains spaces.

Available methods

  • Only available for the drupal-method

Examples

  • phab --config=local drupal cache:rebuild
  • phab --config=local drupal "generate:module --module helloworld"

Jump to heading composer

phab --config=<config> composer "<composer-command>"

This command will execute a composer command on the remote host specified in <config>. Please note, that you'll have to quote the composer-command when it contains spaces.

Available methods

  • Only available for the composer-method

Examples

  • phab --config=staging composer "require drupal/module_name"
  • phab --config=local composer update
  • phab --config=production composer "install --no-dev"

Jump to heading encrypt

phab encrypt <source> <target>
phab encrypt <source> <target> --password=<password>

This command will encrypt a list of files with a password. The source files will be encrypted and stored in the target location. If no password is provided, phab will prompt for one.

Examples

  • phab encrypt secrets.txt secrets.txt.enc will encrypt secrets.txt and prompt for a password
  • phab encrypt config.yaml config.yaml.enc --password=mypassword will encrypt with the specified password

Jump to heading platform

phab --config=<config> platform <command>

Runs a specific platform-command.

Jump to heading get:file

phab --config=<config> get:file <path-to-remote-file>

Copy a remote file to the current working directory of your current machine.

Jump to heading put:file

phab --config=<config> put:file <path-to-local-file>
phab --config=<config> put:file <path-to-local-file> --destination <remote-destination>

Copies a local path-to-local-file to a remote instance specified by the configuration. You can specify the full path and filename by providing the --destination option, relative paths are relative to the rootFolder-config of the remote instance.

Per default phab copies the file to the specified rootFolder from the given configuration and it keeps the filename.

Existing files will be overridden without warning.

Configuration

  • this command will use the rootFolder-host-setting for the destination directory, if no destination is given.

Jump to heading get:files-dump

phab --config=<config> get:files-dump

This command will tar all files in filesFolder and privateFilesFolder and download it to the local computer.

Available methods

  • currently only implemented for the files-method

Jump to heading get:sql-dump

phab --config=<config> get:sql-dump

Get a current dump of the remote database and copy it to the local machine into the current working directory.

Available methods

  • mysql
  • sqlite

Jump to heading restore:sql-from-file

phab --config=<config> restore:sql-from-file <path-to-local-sql-dump>
phab --config=<config> restore:sql-from-file <path-to-local-sql-dump> --skip-drop-db

This command will copy the dump-file path-to-local-sql-dump to the remote machine, drop the database (if the --skip-drop-db-option is not passed) and import it into the database.

Available methods

  • mysql
  • sqlite

Jump to heading script

phab --config=<config> script <script-name>

This command will run custom scripts on a remote machine. You can declare scripts globally or per host. If the script-name can't be found in the fabfile.yaml you'll get a list of all available scripts.

Additional arguments get passed to the script. See the examples.

Examples

  • phab --config=mbb script. List all available scripts for configuration mbb
  • phab --config=mbb script behat Run the behat-script
  • phab --config=mbb script behat "--name="Login feature" --format=pretty" Run the behat-test, apply --name and --format parameters to the script

The script-command is rather powerful, have a read about it in the extra section.

Jump to heading docker

phab --config=<config> docker <docker-subcommand>

The docker command is suitable for orchestrating and administering remote instances of docker-containers. The basic setup is that your host-configuration has a docker-section, which contains a configuration-key. The dockerHosts-section of your fabfile.yaml has a list of commands which are executed on the "parent-host" of the configuration. Please have a look at the docker-section for more information.

Most of the time the docker-container do not have a public or known ip-address. phabalicious tries to find out the ip-address of a given instance and use that for communicating with its services.

There are three implicit subcommands available:

Jump to heading copySSHKeys

phab --config=mbb docker copySSHKeys

This will copy the ssh-keys into the docker-instance. You'll need to provide the paths to the files via the three configurations:

  • dockerKeyFile, the path to the private ssh-key to use.
  • dockerAuthorizedKeysFile, the path to the file for authoried_keys or a url.
  • dockerKnownHostsFile, the path to the file for known_hosts
  • dockerNetRcFile, the path to a .netrc-file to copy into the container. This is helpful if you are using https-repositories and want to authenticate against them.

As docker-container do not have any state, this command is used to copy any necessary ssh-configuration into the docker-container, so communication per ssh does not need any passwords.

Jump to heading waitForServices

This command will try to run supervisorctl status in the container and waits until all services are running. This is useful in scripts to wait for any services that need some time to start up. This command depends on supervisorctl.

Jump to heading start-remote-access

phab --config=<config> start-remote-access
phab --config=<config> start-remote-access \
  --port=<port> \
  --public-port=<public-port> \
  --public-ip=<public-ip>

This command will run a command to forward a local port to a remote port. It starts a new ssh-session which will do the forwarding. When finished, type exit.

Examples

  • phab --config=mbb start-remote-access will forward localhost:8888 to port 80 of the docker-container
  • phab --config=mbb start-remote-access --port=3306 --public-port=33060 will forward localhost:33060to port 3306

Jump to heading docker-compose

phab --config=<config> docker-compose <docker-compose-arguments>

The docker-compose-command will run docker-compose in the mentioned environment, passing all given arguments to it. Phab will also set all environment variables beforehand.

Some examples:

phab -cmbb docker-compose ps
phab -cmbb docker-compose -- exec web ls -la
phab -clive docker-compose run e2e

Jump to heading notify

phab --config=<config> notify <message> <channel>

This command will send the notification <message> to Mattermosts channel <channel>. For a detailed description have a look into the dedicated documentation.

Examples

  • phab config:mbb notify "hello world" "off-topic": sends hello world to #off-topic

Jump to heading app:scaffold

phab app:scaffold <path/url-to-scaffold-files> \
  --name=<name of app> \
  --short-name="short name of app" \
  --output=<path to output> \
  --override="1|0"

This command will scaffold a new project from a set of scaffold-files. The scaffold-file might contain questions to set options. Values for these questions can be set via environment variables (in upper case snake case) or by passing them via the command line options (using kebab-case).

For more information about scaffolding new apps, please visit the dedicated documentation.

Examples

  • phab app:scaffold path/to/scaffold.yml will scaffold the app in the current folder. Phab will ask for the name and the short-name
  • phab app:scaffold path/to/scaffold.yml --name="Hello World" --short-name="HW" will scaffold the app with name "Hello World and short-name "HW"
  • phab app:scaffold https://config.factorial.io/scaffold/d9/d9.yml will scaffold a Drupal 9 app from the remote configuration
  • phab app:scaffold https://config.factorial.io/scaffold/d9/d9.yml --name "test drupal" --short-name td --php-version 8.1 will scaffold with predefined options

Jump to heading app:create

phab --config=<config> app:create
phab --config=<config> app:create --copy-from=<other-config>
phab --blueprint=<blueprint-name> --config=<config> app:create
phab --config=<config> app:create --force

This command will create a new app instance from an existing config. Phabalicious executes a list of customizable stages:

  • preparing the destination
  • install the current code base
  • start the application
  • install its dependencies
  • install the app

Behavior:

  • If the target directory already exists, phab will prompt for confirmation (unless --force is used)
  • If phab detects an already created app (via .projectCreated lock file), it will deploy the current application instead of creating a new one
  • After creation completes, phab will run either copy-from (if --copy-from option provided) or reset
  • The stages can be customized via the appStages.create configuration setting

Options:

  • --copy-from=<other-config> - Copy data from another configuration after creation
  • --force - Skip confirmation prompt if target directory exists

Most useful with blueprints - Using blueprints makes it possible to create a new application which is derived from a single variable (most often the branch name). Useful for feature-based deployments.

For a deeper explanation please have a look into the dedicated documentation

Jump to heading app:update

phab --config=<config> app:update

This command will update the code-base to the latest changes. When using the drush-method, Drupal core will be updated to the latest version (but only if composer is not used). If using composer, then composer will be used to update the existing code.

Available methods

  • drush will update Drupal-core, but only if composer is not used
  • composer will update the codebase by running composer update

Jump to heading app:destroy

phab --config=<config> app:destroy
phab --blueprint=<blueprint-name> --config=<config> app:destroy

This command will destroy an existing app from a given configuration. The process executes several stages:

  • spin down the application
  • delete the containers/pods
  • delete the code base

Using blueprints makes it possible to delete an existing application which is derived from a single variable (most often the branch name). Useful for feature-based deployments.

Caution: there will be no backup!

For more information please have a look into the dedicated documentation

Jump to heading self-update

phab self-update
phab self-update --allow-unstable=1

This will download the latest version of phab and replace the current installed one with the downloaded version. If allow-unstable is set, the latest-dev-version will be downloaded.

Jump to heading jira

phab jira

This command will display your open command for that given project. For this to work, the command needs some configuration-options.

Jump to heading webhook

phab webhook --config hostA
phab webhook nameOfWebhook --config hostA
phab webhook nameOfWebhook --arguments foo=bar --arguments token=my-token --config hostA

This command will invoke the webhook named nameOfWebhook and pass the optional arguments to it. Omitting the name of the webhook will list all available webhooks. Have a look into the webhook-documentation.

Jump to heading npm

phab npm run build:css --config hostA
phab npm run lint --config hostB

This will run an npm command on the given configuration. Make sure, that your host config has npm as a need a npm.rootFolder points to the folder containing package.json.

Jump to heading yarn

phab yarn build:css --config hostA
phab yarn lint --config hostB

This will run a yarn command on the given configuration. Make sure, that your host config has yarn as a need a yarn.rootFolder points to the folder containing package.json.

Jump to heading variable:pull

phab -chost variable:pull path/to/yaml.file

This will pull all variables listed in path/to/yaml.file and put the values into the yaml file and store it again. (Works currently only for D7). variable:pull and variable:push are useful to retrieve a list of variables and restore them at some point in the future.

Jump to heading variable:push

phab -chost variable:push path/to/yaml.file

This will push all variables listed in path/to/yaml.file and set them on the remote instance. (Works currently only for D7)

Jump to heading k8s

Runs a command against a kubernetes cluster. More info here

Jump to heading artisan

Runs a laravel artisan command

phab -chost artisan db:seed
phab -chost artisan migrate

Jump to heading db:install

phab -chost db:install

This command will install a new database.

Jump to heading db:drop

phab -chost db:drop

This command will drop all tables in a database.

Jump to heading db:query

phab -chost db:query "<sql-query>"

This command will run a query against the database and display the results.

Examples

  • phab -chost db:query "SELECT * FROM users LIMIT 10"
  • phab -chost db:query "SHOW TABLES"

Jump to heading db:shell

phab -chost db:shell

This command will connect the user to a running database client (e.g. mysql) so the user can run interactive commands against the db.

phab -chost db:shell:command

This command will print the shell commands necessary to run so that the user can connect to the db client directly.

Jump to heading restic

phab -cmy-config restic -- snapshots
phab -cmy-config restic -- restore <snapshot-id>
phab -cmy-config restic -- snapshots --host-name my-hostname
phab -cmy-config restic -- forget --prune --keep-daily=14 --keep-weekly=4 \
  --keep-monthly=6 --group-by host --prune

If your host has restic listed as its needs then restic will be used to run offsite-backups. You can interact with your restic repository using the restic-command. All given arguments and options will be passed down to restic, enriched with the configuration stored in the fabfile (See also).

Jump to heading workspace:create / workspace:update

Please refer to the dedicated page here