/delta-cli-tools

Command-line tools used at Delta Systems for common development workflow needs.

Primary LanguagePHPBSD 2-Clause "Simplified" LicenseBSD-2-Clause

Delta Systems CLI Tools

Command-line tools used at Delta Systems for common development workflow needs.

Installation

Watch the brief installation tutorial video if you'd like a bit more help getting Composer installed globally and added to your shell's $PATH: https://youtu.be/JTM429G2fps.

  1. Install Composer globally (https://getcomposer.org/doc/00-intro.md#globally).
  2. Add $HOME/.composer/vendor/bin/ to your $PATH.
  3. Install the Delta CLI tools by running composer global require deltasystems/delta-cli
  4. Change to your project's directory and run delta to get started.

Configuring Your Project

All CLI tools configuration is done via the delta-cli.php file. You can generate one for your project using the create-project-config command:

delta create-project-config

At this point, the generated file will be quite sparse. It will just have your project's name.

Typically, the first thing you'll want to do in delta-cli.php is configure the environments and deployment script for your project. Take a look at the example delta-cli.php file to get started (https://github.com/DeltaSystems/delta-cli-tools/blob/master/delta-cli.php).

Some key concepts to note from the example:

  1. You can pass a shell command directly to addStep(). You can either pass just the command or you can provide two arguments: a step name and your command.
  2. You can do the same with any valid PHP callable (an inline Closure or any class method, for example).
  3. You can specify some steps as being specific to only some of your environments.
  4. While the deploy script is built-in, you can add custom scripts with the same API.
  5. You can call one script from another script. (See composing-scripts in the example.)

Whenever you're running a CLI tools script, you have some options available to you that are worth noting:

  1. The environment name is the primary required argument. Example: delta my-script production.
  2. --skip-step=[STEP-NAME]: Allows you to skip one or more steps in the script.
  3. --dry-run: Will attempt to perform a dry run. Steps that don't support it will be skipped.
  4. --list-steps: Will just list the steps in a script rather than trying to run them. (Helpful especially if many steps were added by a template rather than directly in your delta-cli.php.)

What's next?

The CLI tools project is still quite young. In the near future, we'll be working on these additions:

  1. More step types. Currently, you can add PHP callbacks and shell commands to your scripts. We plan to add specialized steps for rsync, checking for common issues, etc.
  2. Templates for common environments like WordPress and Zend Framework.
  3. Build out the environment API. We will add things like credentials and host names to the environment objects so that script steps don't have to be specified repeatedly.
  4. The ability to notify people after a script has been run.