---
updatedAt: 2025-12-04T11:28:46.000Z
agentTools:
  projectIndex: https://developer.didimo.co/llms.txt
---

# Headless and CLI

Automate Crowd Generation Pipelines with Command Line and Continuos Integration 

**Popul8 CLI** is a command-line tool that extends **Popul8**’s functionality directly from your terminal. It is supported on both **Windows** and **macOS**.

## Installing the CLI

### macOS

1. Double-click `.dmg` to begin the installation ([book a demo](https://www.didimo.co/book-a-demo) to access Popul8).
2. Navigate to the CLI folder. If the Contents folder is not visible, right-click in **Popul8.app** and select **Show Package Contents**.

```
/Applications/Popul8.app/Contents/Cli/popul8-cli
```

3. Open **Terminal** and drag and drop the `popul8-cli` file into it, and press **Enter** to start the `popul8-cli`.

### Windows

1. Install Popul8 ([book a demo](https://www.didimo.co/book-a-demo) to access Popul8).
2. Navigate to the installation folder. By default, this is:

```
C:\Program Files (x86)\Popul8`
```

3. Locate the `install-cli.exe`file, drag it into your terminal, and press **Enter** to start the installation.

## How To Use

Popul8 CLI can either launch a new unattended Popul8 process, without GUI, or connect to an existing Popul8 process.

The general syntax is:

```shell
popul8-cli [command] [options]
```

<Image align="center" border={true} width="600px" src="https://files.readme.io/9927968831aba516c10d4077a50f04b022a9039e725741c91ade081fc5140c8a-Screenshot_2025-10-28_at_10.09.37.png" className="border" />

## Supported Commands

| Command | Description                                                                |
| :------ | :------------------------------------------------------------------------- |
| start   | Starts **Popul8** in headless mode                                         |
| stop    | Stops the currently running Popul8 session                                 |
| open    | Opens a project, using its **.pp8** file full path                         |
| export  | Exports all the crowds available in the open project                       |
| verify  | Exports a html report with all the intersections found in the open project |
| config  | Show or save configurations                                                |
| status  | Checks if **Popul8** is currently running                                  |
| license | Sets a specific license file for the currently running **Popul8** process  |
| version | Show **CLI** and **Popul8** version                                        |

<br />

## Command Details

### status

Checks if **Popul8** is currently running.

#### Syntax

```shell
popul8-cli status
```

### start

Starts **Popul8** in headless mode.

#### Syntax

```shell
popul8-cli start [<full/path/to/binary>]
```

### license

Sets a specific license file for the currently running **Popul8** process.

#### Syntax

```shell
popul8-cli license <full/path/to/license/file>
```

### open

Opens a project, using its `.pp8` file full path.

#### Syntax

```shell
popul8-cli open <full/path/to/project/file.pp8>
```

### verify

Exports a html report with all the intersections found in the open project.

Optional `--scope` or `-i`: Allowed values: `all`, `shapes` and `templates` (default)

#### Syntax

```shell
popul8-cli verify <full/path/to/export/folder> [-i scope]
```

### export

Exports all the crowds available in the open project.

#### Syntax

```shell
popul8-cli export <full/path/to/export/folder>
```

### stop

Stops the currently running **Popul8** session.

#### Syntax

```shell
popul8-cli stop
```

<br />

## Example

```shell
> popul8-cli start
Popul8 is running
> popul8-cli license /home/user/private/popul8/license.bin
OK
> popul8-cli status
Popul8 is running
License Status: OK Valid
> popul8-cli open /home/user/popul8-projects/project.pp8
OK
> popul8-cli verify /home/user/Documents/project-exports -i templates
OK
> popul8-cli export /home/user/Documents/project-exports
OK
> popul8-cli stop
Popul8 stopped
```