# Get started - Cover CLI

Get started with Diffblue Cover CLI - in short, install the CLI tool, apply your license, and you're ready to go. This topic also provides an example and some next steps.

If you've already done this as part of your free trial, you may want to skip this and jump straight to the [cover-cli](https://cover-docs.diffblue.com/features/cover-cli "mention") details, or perhaps you want to update to the latest version - see [update-cover](https://cover-docs.diffblue.com/get-started/update-cover "mention").

## eLearning

**Short on time?** If you'd like a fast-track experience check out our getting started video. \[6 min]

{% embed url="<https://youtu.be/eZkDQsYM9fA>" %}

## 1. Install Diffblue Cover CLI

{% tabs %}
{% tab title="Windows" %}

1. Download the latest version of Diffblue Cover CLI `.exe` installer or `.zip` file:\
   \
   \- Download directly [here using this link](https://release.diffblue.com/cli/latest)\
   \
   \- From your organization's internal file/app store.\\
2. If you use the installer, run the `.exe` installer and follow the on-screen prompts - during installation you can select where to install Diffblue Cover.
3. If you use the archive file, extract the `.zip` file to an appropriate installation folder. Add the install folder path to your `PATH` environment variable or create a new `%DCOVER%` environment variable and add that to `PATH`.
4. When you're done, restart your PC. Once complete, open Windows PowerShell and enter `dcover version` to check the install and `PATH` configuration - if all is OK, Cover will display the current version.
   {% endtab %}

{% tab title="Linux/macOS" %}

1. Download the latest version of Diffblue Cover CLI `.zip` file from:\
   \
   \- Download directly [here using this link](https://release.diffblue.com/cli/latest)\
   \
   \- From your organization's internal file/app store.\\
2. Unzip the Cover CLI zip file to an appropriate installation location (for example, `~/bin`) and add this location in the `PATH` environment variable using the following example commands:\\

   ```
   mkdir ~/bin
   cd ~/bin
   unzip ~/diffblue-cover*.zip
   export PATH=$PATH:~/bin
   ```

   \
   **Reminder:** Make sure that the `PATH` environment variable is set permanently according to your operating system instructions.
3. Once complete, run `dcover version` to check the install and `PATH` configuration - if all is OK, Cover will display the current version.
   {% endtab %}
   {% endtabs %}

## 2. Apply a license

Diffblue Cover requires a remote license check with the Diffblue licensing server each time it's used. For help troubleshooting license keys, network connections, and proxy server settings, as well as details of offline licensing (Enterprise Edition only), see [licensing](https://cover-docs.diffblue.com/get-started/licensing "mention").

* To activate your license, open Windows PowerShell (Windows) or Terminal (macOS/Linux) and enter the command `dcover activate <license-key>` - replace `<license-key>` with the license key provided in your welcome email or provided by your organization.
* Entering multiple different license keys will overwrite the existing key.
* You can check your license status by running the command `dcover license`

## 3. Try it out

Four steps to automatically write tests - check out a few basics, clone an example project, compile the project and check your environment, and finally, one command to write tests - done.

### Step 1 - A few basics

We won't cover every CLI command option, but here are a few details to get you started:

<table><thead><tr><th width="210.49071125607543">Command</th><th>Description</th></tr></thead><tbody><tr><td><code>dcover help</code></td><td><strong>Help</strong> - get, err, help. Use this with the other commands as well to get some details of what options are available (like <code>dcover help create</code> to get details of the available optional arguments).</td></tr><tr><td><code>dcover activate</code><br><code>&#x3C;license-key></code></td><td><strong>Activate License</strong> - apply/activate a license. Replace <code>&#x3C;lic-key></code> with the license key provided in your welcome email or provided by your organization.</td></tr><tr><td><code>dcover license</code></td><td><strong>Check License</strong> - display your current license status.</td></tr><tr><td><code>dcover version</code></td><td><strong>Check Version</strong> - display the version of Diffblue Cover CLI.</td></tr><tr><td><code>dcover create</code></td><td><strong>Create Tests</strong> - write tests for the project (run from the root directory of the project). You can restrict this further by simply specifying the method or class path - this is detailed a little further in the example in Step 4 below.</td></tr><tr><td><code>dcover create</code><br><code>--&#x3C;arguments></code></td><td><strong>Optional Arguments</strong> - there's a few, OK quite a lot. The optional arguments provide access to deeper functionality within Cover CLI such as creating coverage reports, specifying a build configuration file, and running preflight checks (this one is used in Step 3 below).</td></tr></tbody></table>

### Step 2 - Clone the example project Spring PetClinic

We're going to make use of an example project (Spring PetClinic) to show Diffblue Cover CLI at work. First, we'll clone the project from the Git repo:

{% tabs %}
{% tab title="IntelliJ UI" %}
From IntelliJ select `File > New... > Project from version control`.

* Ensure `Git` is selected in `Version control`.
* Enter `https://github.com/diffblue/demo-spring-petclinic` as the URL.
* Select the directory/folder to clone the project to.
* When you're ready, click `Clone`.

<div align="left"><figure><img src="https://1243928156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ7l8pn8qoIC3ubiJzuaF%2Fuploads%2Fgit-blob-7291c15df555939f4ee3f9f2dca577882fca0bbc%2FIDEClonePetclinic.jpg?alt=media&#x26;token=1517f9f0-f848-409e-9abf-3f4e4886fd72" alt="" width="375"><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Git CLI" %}

1. Open a command line and navigate to where you want to clone this project.
2. Run the following command:

```git
git clone https://github.com/diffblue/demo-spring-petclinic
```

{% endtab %}
{% endtabs %}

### Step 3 - Compile the project and check your environment

Before we write any tests, we need to compile the PetClinic project. Diffblue Cover works by analyzing the bytecode of any project used with Cover. Open a command line, navigate to the directory containing the PetClinic project, and run the Maven `install` command:

```
cd demo-spring-petclinic
./mvnw install
```

**Basic prerequisites:**

* Java 8, 11, 17, or 21 compatible source code, or Kotlin source code.
* Maven 3.2.5+ or Gradle 4.9+ build tools.
* The project (for use with Diffblue Cover) must compile and run with no failing unit tests.

  JUnit and TestNG testing frameworks are supported.
* For the best results, your project needs to be completely built from the root.

**More details:**

Diffblue Cover requires that the system environment (hardware, operating system, network connectivity, Java installation) as well as the project environment (build tooling, dependencies, presence of artifacts, existing unit tests) meet the minimum requirements as detailed in [specs-and-reqs](https://cover-docs.diffblue.com/get-started/specs-and-reqs "mention"). Cover CLI will perform an environment check before analysis begins to ensure that the requirements are met - if there are any issues, these will be reported via the Diffblue Cover panel in IntelliJ using E(Environment) [output-codes](https://cover-docs.diffblue.com/features/output-codes "mention").

Further details can be found in the [Compiling your project successfully](https://cover-docs.diffblue.com/features/cover-cli/project-configuration/compiling-your-project) section.

**Check your environment:**

Cover CLI also provides a command line option to run these checks, without writing any tests, useful when you just want to check-out your environment without doing anything else. To run a preflight environment check, open a command line, navigate to the directory containing the PetClinic project, and run the preflight checks:

```
cd demo-spring-petclinic
dcover create --preflight
```

### Step 4 - Automatically write tests for the example project

Initially, we'll create tests for the `OwnerController` class:

```
dcover create org.springframework.samples.petclinic.owner.OwnerController
```

And that's it, simple - 1 command line, 9 methods analyzed, 14 tests written, around 340 lines of code created, and all in around 65 seconds - computationally perfect, human readable. You'll find these tests in:

`demo-spring-petclinic/src/test/java/org/springframework/`\
`samples/petclinic/owner/OwnerControllerDiffblueTest.java`

```java
package org.springframework.samples.petclinic.owner;

import ...

@ContextConfiguration(classes = {OwnerController.class})
@ExtendWith(SpringExtension.class)
class OwnerControllerDiffblueTest {
	@Autowired
	private OwnerController ownerController;

	@MockBean
	private OwnerRepository ownerRepository;

	/**
	 * Method under test: {@link OwnerController#initCreationForm(Map)}
	 */
	@Test
	void diffbluetestInitCreationForm() throws Exception {
		MockHttpServletRequestBuilder requestBuilder = MockMvcRequestBuilders.get("/owners/new");
		MockMvcBuilders.standaloneSetup(ownerController)
			.build()
			.perform(requestBuilder)
			.andExpect(MockMvcResultMatchers.status().isOk())
			.andExpect(MockMvcResultMatchers.model().size(1))
			.andExpect(MockMvcResultMatchers.model().attributeExists("owner"))
			.andExpect(MockMvcResultMatchers.view().name("owners/createOrUpdateOwnerForm"))
			.andExpect(MockMvcResultMatchers.forwardedUrl("owners/createOrUpdateOwnerForm"));
	}

....
```

Once you're happy with this first set of tests, create the full test suite for the entire PetClinic project:

```
dcover create
```

That's it, two "words" and you're done. Of course this one takes a **little** longer to complete (approx. 5 minutes) as it creates tests across the entire PetClinic project, analyzing 97 methods and creating 77 tests (exact count may vary slightly). To take a look at the tests, open a `xxxDiffblueTest.java` file in your IDE of choice (these files are saved to the `/src/test/java` directory structure by default).

Note that the examples here use `DiffblueTest` as the default class name suffix and `diffbluetest` as the default method name prefix, just to highlight the tests created by Diffblue Cover. To change your suffix and prefix, use the `--class-name-template` and `--method-name-template` command arguments - see Cover CLI [commands-and-arguments](https://cover-docs.diffblue.com/features/cover-cli/commands-and-arguments "mention") for details.

## More...

### What does Cover CLI do?

<div align="left"><figure><img src="https://1243928156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ7l8pn8qoIC3ubiJzuaF%2Fuploads%2Fgit-blob-84f1e2ad9e35e66fafbeb7a6b37c352a47bb8502%2FDiffblueCoverCoreProcess-2024.jpg?alt=media" alt=""><figcaption></figcaption></figure></div>

* Diffblue Cover first ensures that your code is compiled and examines each method that Cover will create tests for, including any dependent methods.
* Cover then creates initial test candidates and uses reinforcement learning to evaluate and adjust the test candidate for each method. This process is repeated until the set of tests that optimize coverage are selected and committed to your code base.

### Next steps

Now you're up and running with Cover CLI:

* Have a scan through the [test-examples](https://cover-docs.diffblue.com/features/cover-plugin/writing-tests/test-examples "mention") topic which provides some additional source code examples along with an explanation of the tests created by Diffblue Cover.
* Create some tests for your own project - as long as you have a project that compiles and your environment meets the Cover [prerequisites](https://cover-docs.diffblue.com/get-started/specs-and-reqs), you're literally a single command line away from AI written tests, created in seconds instead of hours.
* See [cover-cli](https://cover-docs.diffblue.com/features/cover-cli "mention") to familiarize yourself with the full set of CLI features and functions.

### Diffblue Cover - one AI

Diffblue Cover is also provided as an IDE plugin tool so you can write tests with one click in the IntelliJ IDE (see [get-started-cover-plugin](https://cover-docs.diffblue.com/get-started/get-started/get-started-cover-plugin "mention")), and can also be integrated into your CI pipeline to automatically write tests within your CI workflow (see [get-started-cover-pipeline](https://cover-docs.diffblue.com/get-started/get-started/get-started-cover-pipeline "mention")).

But Cover CLI, Cover Plugin, and Cover Pipeline are not mutually exclusive, in fact they make perfect partners. Use Cover Plugin within the IntelliJ IDE to write and check unit tests for your application during development, and also use Cover CLI directly from the IntelliJ Console or your OS command line to access the wider and deeper functionality provided by Cover CLI - finally, use Cover Pipeline within your CI tool to automate the whole process and provide consistency across your organization.

<div align="left"><figure><img src="https://1243928156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ7l8pn8qoIC3ubiJzuaF%2Fuploads%2Fgit-blob-bbc3072c6b8edff0fe74bf911a3d96d5051c15ad%2FWorkflow-PluginCLI-2024.jpg?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>