Introduction

Meet tj, a tool that helps you create new local WordPress development sites, manage existing sites, and deploy them, all from the command line.

tj handles all of the hard stuff: creation of a local development environment, managing local and remote WordPress sites, and the most annoying part of all, actually deploying those sites. Say goodbye to MAMP!

tj is built on top of tried and true open source libraries such as Capistrano for deployment, Vagrant for local development, and even a little bit of WP-CLI for database migration.

Requirements

tj requires Vagrant and VirtualBox to be able to create virtual machines for local development. Please download and install both of these before getting started. If you plan on using tj for deployments, you should also ensure that your remote servers have WP-CLI installed in order for tj to be able to handle database migration.

I recommend one of the latest versions of Ruby MRI (2.2, 2.1, 2.0). tj requires at least MRI 1.9.3. For the full report, check out the Travis CI build status, where I test against an array of Ruby interpreters.

I also recommend you set up SSH-keys for GitHub. Internally, tj uses git clone with SSH URLs, so things might break if you don't have your keys set up properly.

Installation

gem install theme-juice

NAME

tj - WordPress development made easy

SYNOPSIS

tj [command] [--flag=arg] [--flag]

GLOBAL OPTIONS

--vm-box=repository

Force vagrant(1) box for use as VM*

--vm-path=path

Force path to VM*

--vm-ip=ip

Force IP address of VM*

--vm-prefix=string

Force directory prefix for project in VM*

--vm-revision=revision

Revision hash or branch to checkout for VM (default is master)

--from-path, --in-path=path

Run Juicefile(5) commands from the passed path instead of from the current directory.

--from-srv, --in-srv=path

Run Juicefile(5) commands from the passed srv path instead of from the current host directory path when using the --inside-vm flag.

--inside-vm, --in-vm

Run Juicefile(5) commands from inside of the virtual machine instead of your host machine.

--yolo, --yes

Say yes to anything and everything, and maybe even get a few surprises

--boring

Prints all output without any fancy formatting

--no-unicode

Prints all output without unicode characters

--no-colors, --no-color

Prints all output without color

--no-animations

Prints all output without animations**

--robot

Prints all output with absolutely no formatting

--no-landrush

Disable the landrush(1) gem for managing DNS*

--no-port-forward, --no-port-forwarding

Disable automatic port forwarding*

--verbose

Prints out additional logging information

--quiet, --shh

Suppresses all command output

--trace

Raises any exceptions caught during runtime

--dryrun, --dry-run

Run a command without actually doing anything

--nginx, --no-apache

Create conf files for nginx(7) instead of apache(7)*

* Flag is really only applicable on init(1) before the VM has been created, unless a new (unused) vm-path is specified.

** Coming soon (possibly)

PRIMARY COMMANDS

Run tj help [command] to view an individual command's man page.

init(1), up

Initialize the VM

create(1), new, mk

Create a new project (also runs init(1) if VM is uninitialized)

setup(1)

Setup an existing project (alias for create(1) --bare)

delete(1), rm, remove, trash

Delete a project

deploy(1), server, remote

Deploy and manage a project

update

Update virtual machine and dependencies

SECONDARY COMMANDS

version, --version, -v

Print the current version

env, --env=[property]

Print environment properties

list, ls, projects, apps, sites

List all projects

vm, vagrant, vvv=[command[,command]...]

Manage development environment via vagrant(1). Commands are proxied to your Vagrant installation so that they can be run from any directory.

CONFIG FILE

A YAML configuration file called a Juicefile(5) can be used to store commonly used build scripts, similar to npm(1) scripts. Each command can be mapped to any build script you like, allowing you to define a set of commands that can be used across all of your projects. If you plan to deploy using tj, this file will also house your deploy(1) configuration.

For reference, below is an example config:

  # Project configuration
  project:
    name: example
    url: example.dev

  # Manage command aliases for the current project
  commands:

    # Run project install scripts
    install:
      - npm install
      - grunt build

    # Manage build tools
    dev:
      - grunt %args%

    # Manage front-end dependencies
    assets:
      - npm %args%

    # Manage back-end dependencies
    vendor:
      - composer %args%

    # Create a backup of the current database with a nice timestamp
    backup:
      - mkdir -p backup
      - wp @dev db export backup/$(date +'%Y-%m-%d-%H-%M-%S').sql

  # Manage deployment settings for the current project
  deployment:
    # ...

    stages:
      # ...

CONFIG COMMANDS

The commands within the commands block can be run from the command line via tj <command>. For example, we can run the dev command by running tj dev, which will in turn run the command grunt.

If you noticed in the example above, there are a few commands that contain %args%; each command list is run within a single execution via joining: cmd1 && cmd2 [&& cmd3...], with all %args%/%argN% being replaced with the corresponding argument index, when available.

Here's a few example commands using placeholders:

  example-command:
    # Will contain all arguments joined by a space
    - cmd1 %args%
    # Will contain each argument mapped to its respective index
    - cmd2 '%arg1% %arg2% %arg3%'
    # Will only map argument 4, while ignoring 1-3
    - cmd3 "%arg4%"

To clarify a little bit more, we could run tj dev build, and since our dev command contains %args%, that will in turn run the command grunt build; if we run tj dev some:other task, that would be interpreted and run as grunt some:other task.

You can specify an unlimited number of commands with an unlimited number of arguments within your Juicefile; however, you should be careful with how this is used. Don't go including sudo rm -rf %arg1% in a command, while passing / as an argument. Keep it simple. These are meant to make your life easier by helping you manage build tools, not to do fancy scripting.

CONFIG TEMPLATE STRINGS

You may define ERB template strings within a project starter template's Juicefile(5). These will be replaced upon running create(1).

For example,

  # Project configuration
  project:
    name: <%= name %>
    url: <%= url %>

will be replaced with,

  # Project configuration
  project:
    name: example-project
    url: example-project.dev

if those were the options chosen during a creation. The following variables are available for use:

  • name: Project name

  • location: Project location

  • url: Project URL

  • xip_url: Project xip.io URL

  • template: Project template repository URL

  • repository: Initialized repository URL, if available

  • db_host: Project database host

  • db_name: Project database name

  • db_user: Project database user

  • db_pass: Project database password

  • db_import: Path to imported database file

  • vm_box: Virtual machine box URL

  • vm_ip: Virtual machine IP address

  • vm_revision Revision hash or branch of VM

  • vm_path: Virtual machine location on the host machine

  • vm_root: Web root of the VM on the host machine

  • vm_location: Project location within the VM on the host machine

  • vm_srv: Project location within the VM on the guest machine

  • vm_prefix: Virtual machine project location prefix

ENVIRONMENT

All of the global options have a corresponding ENV variable that can be set to permanently use the specified value each time tj(1) is run. This is useful if you're using an alternate vagrant(1) box, or if you need to disable certain features due to limited support i.e. on Windows.

TJ_VM_BOX=repository

Force vagrant(1) box for use as VM

TJ_VM_PATH=path

Force path to VM

TJ_VM_IP=ip

Force IP address of VM

TJ_VM_REVISION=revision

Revision hash or branch to checkout for VM (default is master)

TJ_VM_PREFIX=string

Force directory prefix for project in VM

TJ_FROM_PATH=path

Run Juicefile(5) commands from the passed path instead of from the current directory.

TJ_FROM_SRV=path

Run Juicefile(5) commands from the passed srv path instead of from the current host directory path when TJ_INSIDE_VM is enabled.

TJ_INSIDE_VM=bool

Run Juicefile(5) commands from inside of the virtual machine instead of your host machine.

TJ_YOLO=bool

Say yes to anything and everything, and maybe even get a few surprises

TJ_BORING=bool

Prints all output without any fancy formatting

TJ_NO_UNICODE=bool

Prints all output without unicode characters

TJ_NO_COLORS=bool

Prints all output without color

TJ_NO_ANIMATIONS=bool

Prints all output without animations (coming soon)

TJ_NO_LANDRUSH=bool

Disable the landrush(1) gem for managing DNS

TJ_NO_PORT_FORWARD=bool

Disable automatic port forwarding

TJ_VERBOSE=bool

Prints out additional logging information

TJ_QUIET=bool

Suppresses all command output

TJ_TRACE=bool

Raises any exceptions caught during runtime

TJ_DRYRUN=bool

Run a command without actually doing anything

TJ_NGINX=bool

Create conf files for nginx(7) instead of apache(7)