Getting Started

    Before we begin, please register for an account with Theme Juice. After you've registered, access your account dashboard where you can purchase and download the latest version of Theme Juice. Once downloaded, follow the instructions for your OS:

    • Mac: Mount the .dmg file and drag the Theme Juice icon into your /Applications directory.
    • Windows: Coming soon.
    • Linux: Coming soon.

    Interested in staying up to date on when the Windows and Linux versions will launch?

    Granting sudo access

    When opening Theme Juice for the first time, you'll be instructed to do a few things to properly configure your system for development. First, you'll be prompted for your sudo password. We're using a native OS dialog prompt (meaning we have absolutely no access to your credentials), and we only ask so that the app can:

    • properly install any missing dependencies, such as Vagrant, Xcode command line tools, and VirtualBox
    • allow Vagrant to properly forward ports and append to your /etc/hosts file


    After this dialog, you may be prompted to install and/or update Vagrant, Xcode command line tools and VirtualBox. Theme Juice comes pre-packaged with the official installers for those dependencies and will walk you through installation when needed.

    Log into your account

    Before getting started, be sure to log into your Theme Juice account to make sure your application stays up to date via our auto-updater!


    Setup the virtual machine


    First thing's first, you need a local development environment! Our virtual machine, Graft, is a high-quality LAMP development environment, configured specifically for WordPress development. It comes pre-packaged and pre-provisioned, so that you can get up and running as quickly as possible. To download and initialize the Graft repository, click 'Initialize' in the sidebar on the left. This is only done once.


    Now that you've initialized the virtual machine, let's boot it up for the first time! Go ahead and click 'Create' under the 'Virtual Machine' section within the sidebar. Depending on your internet connection speed, this step may take a little while. Vagrant will need to download and configure the Graft virtual machine. Go ahead and grab yourself a nice cup of coffee (or tea, if that's your thing)!

    Creating VM

    Just like the initialization step, this is required only once, unless you decide to destroy your virtual machine and start over (we'll get to that later); and even then, it will be much faster since Vagrant will automatically cache Graft, making sure that you won't have to download it all over again.

    Dashboard and utilities

    Sidebar utilities

    After that completes, you should now be able to access your Graft dashboard! From there, you'll be able to see the specs for your brand new virtual machine. Within the app's sidebar, you should see various tools under 'Utilities' such as PHP info, phpMyAdmin, phpMemcacheAdmin and more!

    Also in the sidebar are actions to manage your virtual machine. Depending on its state, you'll see actions such as, boot, shutdown, restart, provision and destroy. All of these have a specific function, which you can read more about via Vagrant's documentation. If you'd like to access your machine over SSH, it's also just a click away!

    Create your first project

    Let’s get to work! Now that we have your virtual machine up and running, let's create your first project. Click on the 'Create Project' button in the sidebar and let’s get started!

    New project

    Once you click on the button, you'll be presented with a few questions. Let’s take a minute and go through each section and explain what each option is and how it will affect your project:

    • Project name: Give your project a unique name. You may use lowercase letters, numbers and dashes. This will be used as an identifier for your project within the app and virtual machine.
    • Project URL: Define a unique local development domain ending in .dev. Each project will be accessible from the .dev domain of your choosing. Just like the project name, you may use lowercase letters, numbers and dashes, but also subdomains, e.g.
    • Project location: Define what folder you want to use as the root folder for this website. This will be automatically synced to your virtual machine, so that you can continue to develop using your favorite tools. If you select a non-empty directory, Theme Juice will assume you want to perform a creation without a starter template, e.g. setting up an existing project as opposed to creating a brand new project.
    • Project starter template: By default, this is set to use the official WordPress repository. You may also use Sprout, our starter template featuring Sass, PHP Haml and CoffeeScript; or you may use your own starter template. A custom starter template is a good choice if you have a certain set of themes or plugins you prefer to use, if you use a non-standard WordPress folder structure, or if you use development tools such as Composer, Sass, Webpack, Grunt or Gulp.
    • Starter template repository: If you decided to use your own starter template, provide the Git repository URL here. If this is a private repository, please ensure that you have the correct access rights so that Git can properly clone it. If you aren't able to clone it from the command line, Theme Juice won't be able to either.
    • WordPress version: If you decided to use the official WordPress repository, you'll be given the option to select which version of WordPress you'd like to use. This will checkout the corresponding version branch. Need an older version? Let us know and we'll get it added! An alternate way to select older versions is to set your template to "other", specify the official WordPress Git repository and then manually input the branch/release commit you'd like to use.
    • Starter template branch/revision: If you decided to use your own starter template, you have the ability to select a specific commit revision hash or branch to checkout. The default value is to checkout the latest commit on the master branch.
    • Does this project have a Juicefile? If your selected starter template contains a Juicefile, you may enable this feature to run your starter template's install command after cloning it. For example, you can use this feature to run your build tools and install dependencies. If your starter template does not contain a Juicefile or your Juicefile does not contain an install command, please ensure that this is disabled.
    • Is this a WordPress project? Although Theme Juice is designed for WordPress development, it is not limited to it. We've used Theme Juice to develop and deploy static sites, Magento stores, Drupal sites and more. If your project uses a LAMP stack, Theme Juice can probably run it!
    • WordPress config type: Most WordPress installations will use the standard wp-config.php file, but there are alternate WordPress installations such as Sprout and Bedrock that take advantage of a .env file to store environment configuration variables. This allows your WordPress installation to essentially be environment agnostic.
    • Does this project need a wp-cli.local.yml file? Enable this if you would like Theme Juice to create a wp-cli.local.yml file containing SSH configuration, letting you run commands like wp @development plugin list from within your project's root directory. WP-CLI (v0.24+) will automatically SSH into the virtual machine, so that you can run commands from your host machine. To utilize this feature, you are required to have WP-CLI installed on your machine.
    • Does this project need a database? Most projects will likely need a database, but if yours doesn't feel free to disable this one.
    • Do you want to import a database? If you're working on an existing project, you'll likely want to make sure that your development database is up to date with your staging or production database.
    • MySQL database file: Select a .sql database file and Theme Juice will automatically import into your project for you. Please note, that the file does need to be within your project's root directory so that the virtual machine has access to it. You may need to run wp @development search-replace OLD_URL DEV_URL afterwards, if you have not already run a search and replace on your database file. This is because Theme Juice does not know your remote URL in order to automatically perform the search and replace.

    Project dashboard

    Phew! Now that you know the all of the options available, go ahead and create your first project. After creation, you'll be able to access your new project's dashboard from within the sidebar. The project dashboard is where you'll manage each individual project you create.


    If you add a Juicefile configuration, you can configure commands to do anything you need, like back up the database, minify your images, compile Sass, and more. The deployment section can also be configured if you would like to set up SSH deployments for your project (more on that soon).

    Famous 5-minute install

    Now all that's left to do is to visit your new project's domain, and WordPress will walk you through the famous 5-minute install.

    WP installation


    That's all there is to it! Now that you know how to manage your virtual machine and create new projects, go create something awesome! If you find yourself stuck and in need of assistance, feel free to reach out to our support channel.

    Happy coding!