Merge branch 'master' into docs-review-main-doc

docs/source/guides/getting-started/installing-cypress.md

@@ -7,28 +7,84 @@ comments: false
 # {% fa fa-graduation-cap %} What You'll Learn
 
 - How to install Cypress on your project using `npm`
+- How to run Cypress via the command line
+- How to version and automate Cypress via `package.json`
+
 {% endnote %}
 
-# Installing via NPM
+# Installing Cypress via `npm`
 
-Installing Cypress to test your modern web project is as easy as:
+Installing Cypress is easy:
 
 ```shell
+$ cd /your/project/path
 $ npm install cypress --save-dev
 ```
 
-This will...
+This will install Cypress locally for this project, which is ideal for a few reasons:
+- Cypress is a versioned dependency like any other
+- Multiple versions of Cypress can co-exist on the same machine on a per-project basis
+- Simplifies things when you're setting up Continuous Integration
 
-_Aside: Why not install Cypress globally?_
+{% note info What is `npm`? %}
+If you've never set up a NodeJS project before, this is all probably a bit confusing! We recommend heading over to [the NodeJS website](https://nodejs.org/) and digging in, we'll wait.
+{% endnote %}
 
-_Aside: Not familiar with npm?_
+{% note danger Windows: Coming Soon %}
+A big, hearty thanks to all of our patient early adopters avidly awaiting the development of the Windows version of Cypress! If this is you, feel free to follow [this issue](https://github.com/cypress-io/cypress/issues/74) to be notified when Windows support lands.
+{% endnote %}
 
-To run Cypress...
+# Running Cypress via the CLI
 
-_Aside: link to GUI overview doc_
+Cypress has now been installed to our `./node_modules` directory, with its binary executable accessible from `./node_modules/.bin`. This means we can call it from our project root like so:
 
-To automate running Cypress with `package.json`...
+```bash
+# the long way with the full path
+$ ./node_modules/.bin/cypress open
+# same, shortcut using `npm bin`
+$ $(npm bin)/cypress open
+```
 
-## Windows Support Coming Soon
+After a moment, the Cypress graphical application will launch. If this is your first time running Cypress in this project, it will generate some files to help you get started. These files live in the new `./cypress` directory (also generated for you), and are very user friendly so don't be afraid have a look through them!
 
-A big, hearty thanks to all of our early adopters who support the development of the Windows version of Cypress! If this is you, feel free to follow this issue to be notified when Windows support lands.
+![Cypress First Run Experience](/img/guides/getting-started/installing-cypress/generated-files.png)
+
+# Managing Cypress with `package.json`
+
+Take a look at your `package.json` file, which is where `npm` is configured for your project.
+
+## Versioning Cypress
+
+You should see that Cypress has been added as a development dependency versioned to the latest available version. If you need to install a specific version of Cypress, you can do so by modifying this version string and running `npm install`.
+
+```json
+{
+  ...
+  "devDependencies": {
+    "cypress": "^0.20.0"
+  }
+  ...
+}
+```
+
+## Automating Cypress
+
+In order to run Cypress easily, we recommend having `npm` execute a simple script for you. Do this by adding a `scripts` key to `package.json` with a nested key for the name of the script. For starters, name this script `test`, and have it simply call `cypress open`:
+
+```json
+{
+  ...
+  "scripts": {
+    "test": "cypress open"
+  }
+  ...
+}
+```
+
+Now you can invoke this command like so:
+
+```shell
+$ npm test
+```
+
+...and Cypress will open right up for you!