npm package: @masonite/slab-cli
Description: A local development tool for Masonite websites.
Latest version: 2.0.1

# Slab CLI

[![CircleCI](https://circleci.com/gh/masonitedoors/slab-cli.svg?style=svg)](https://circleci.com/gh/masonitedoors/slab-cli)

## Introduction

Slab CLI is a local web development tool for [Masonite](https://www.masonite.com) websites.

Slab CLI gives you the ability easily replicate a website from a target remote environment and have it available locally on a `*.slab` domain. You can also create new local projects based on defined project types (WordPress, WordPress Multisite, Laravel, Node, etc). Both projects and project types are user defined, making Slab CLI flexible enough any type of project.

## Install

```sh
npm install -g @masonite/slab-cli
```

## Requirements

+ Docker
+ Node 8
+ 2 Restful Endpoints defining projects and project types. (See [Creating Endpoints](#creating-endpoints))

## Usage

### Profiles

Slab CLI is profile based, allowing you to switch between multiple configurations for different teams. Slab CLI requires at least profile to be created. On macOS, profiles configs are located within `~/.slab/profiles/`.

### Commands

#### create

Create a new local project.

#### clone

Clone an existing project defined by the projects endpoint.

#### list

List all available local projects for the current profile.

#### ssh

SSH into a project's docker container as the root user. 

#### profile

Change profiles, create a new profile, or remove an existing profile.

#### open

Opens a project in the default browser when anywhere inside of an existing project. 

#### remove

Remove a local project and it's volumes.

#### doctor

Fixes Slab CLI stuff related to paths and domains.

#### --help

Outputs a list of available commands.

#### --profile

Outputs the current profile name.

#### --version 

Outputs the current version of Slab CLI.

## Creating Endpoints

Slab CLI requires 2 endpoints that define available **projects** and **project types**. These endpoints must be created and hosted somewhere by the user. It is recommended to locally host the projects endpoint on your machine or from inside a local network.

### Template Strings

Slab CLI has a built in templating engine that will convert certain template strings into their corresponding project based values.


|Template String|Description|
|---|---|
| `{{email}}` | The profile's email. This can be used for creating a default user upon site creation. |
| `{{uuid}}` | Each command ran in Slab CLI has a unique identifier. This should be utilized when defining commands to sync content from a remote environment. |
| `{{project_path}}` | The local project's absolute path. |
| `{{project_slug}}` | The local project's unique slug. |
| `{{project_port_1}}` | The local project's port. When cloning a project or creating a new project, Slab CLI assigns an available port to a project. Currently only 1 port is used per project however future version's of Slab CLI may include support for multiple ports.|
| `{{project_url}}` | The local project's url. This is the full url that includes http and the project's port number. You can create an http-less domain by using `{{project_slug}}.slab:{{project_port_1}}` |


### Project Types

The project types endpoint defines the available project types. The example shows a single WordPress install and a WordPress multisite install.

```json
[
	{
		"name": "wordpress",
		"project_repo": "git@github.com:masonitedoors/wordpress-unfinished-slab.git",
		"cmd_before_containers_init": "composer install",
		"cmd_after_containers_init": "sleep 8; docker exec --user=root {{project_slug}} bash -c 'cd /var/www/html; wp config create --dbname=wp --dbuser=web --dbpass=web --skip-check --allow-root; wp db create --allow-root; wp core install --url={{project_url}} --title={{project_slug}} --admin_user=slab --admin_password=slab --admin_email={{email}} --skip-email --allow-root; wp rewrite structure '/%postname%/' --hard --allow-root'",
		"containers": [
			{
				"image": "masonitedoors/lamp",
				"expose": "{{project_port_1}}:80",
				"volumes": [
					"{{project_path}}/html:/var/www/html"
				]
			}
		],
		"files": [
			{
				"filename": ".htaccess",
				"location": "{{project_path}}/html",
				"contents": "# BEGIN WordPress\n<IfModule mod_rewrite.c>\nRewriteEngine On\nRewriteBase /\nRewriteRule ^index\\.php$ - [L]\nRewriteCond %{REQUEST_FILENAME} !-f\nRewriteCond %{REQUEST_FILENAME} !-d\nRewriteRule . /index.php [L]\n</IfModule>\n# END WordPress"
			},
			{
				"filename": "wp-cli.yml",
				"location": "{{project_path}}/html",
				"contents": "apache_modules:\n  - mod_rewrite"
			}
		]
	},
	{
		"name": "wordpress-multisite",
		"project_repo": "git@github.com:masonitedoors/wordpress-unfinished-slab.git",
		"cmd_before_containers_init": "composer install",
		"cmd_after_containers_init": "sleep 8; docker exec --user=root {{project_slug}} bash -c 'cd /var/www/html; wp config create --dbname=wp --dbuser=web --dbpass=web --skip-check --allow-root; wp db create --allow-root; wp core multisite-install --subdomains --url={{project_url}} --title={{project_slug}} --admin_user=slab --admin_password=slab --admin_email={{email}} --skip-email --allow-root;'",
		"containers": [
			{
				"image": "masonitedoors/lamp",
				"expose": "{{project_port_1}}:80",
				"volumes": [
					"{{project_path}}/html:/var/www/html"
				]
			}
		],
		"files": [
			{
				"filename": ".htaccess",
				"location": "{{project_path}}/html",
				"contents": "RewriteEngine On\nRewriteBase /\nRewriteRule ^index\\.php$ - [L]\n\n# add a trailing slash to /wp-admin\nRewriteRule ^wp-admin$ wp-admin/ [R=301,L]\n\nRewriteCond %{REQUEST_FILENAME} -f [OR]\nRewriteCond %{REQUEST_FILENAME} -d\nRewriteRule ^ - [L]\nRewriteRule ^(wp-(content|admin|includes).*) $1 [L]\nRewriteRule ^(.*\\.php)$ $1 [L]\nRewriteRule . index.php [L]"
			},
			{
				"filename": "wp-cli.yml",
				"location": "{{project_path}}/html",
				"contents": "apache_modules:\n  - mod_rewrite"
			}
		]
	}
]
```

### Projects

The projects endpoint defines the projects that available to clone using Slab CLI. These are pre-existing websites that live on a remote webserver. Note that in order to use a project, its type must be previously defined in the **project types** endpoint.

```json
[
	{
		"name": "Project A",
		"slug": "project-a",
		"type": "wordpress",
		"repo": {
			"dev": "git@github.com:masonitedoors/wordpress-unfinished-slab.git"
		},
		"env": [
			{
				"name": "prd",
				"cmd_sync_content": ""
			},
			{
				"name": "dev",
				"cmd_sync_content": ""
			}
		]
	}
]
```


## License

Slab CLI is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT)