# Prolific CLI

The Prolific CLI is a command-line tool for interacting with the Prolific API. It provides a convenient way to manage studies, submissions, and other resources directly from your terminal.

<Warning>
  The Prolific CLI is currently in **beta** and may not fully reflect all API endpoints. The CLI is open source — please contribute and share your ideas.
</Warning>

## Overview

Use the Prolific CLI to:

* Manage studies (create, list, view, update, publish) and submissions
* Manage credentials, filter sets, participant groups, and hooks
* Send and retrieve messages
* Manage workspaces and projects
* Automate common workflows via scripts

The CLI supports both interactive and non-interactive modes, making it suitable for both exploratory use and integration into automated workflows.

## Getting started

The Prolific CLI is available on [GitHub](https://github.com/prolific-oss/cli). Follow the instructions below to install and run it.

### Installation

<Tabs>
  <Tab title="Go Install">
    ```shell
    go install github.com/prolific-oss/cli/cmd/prolific@latest
    ```
  </Tab>

  <Tab title="From source">
    ```shell
    git clone https://github.com/prolific-oss/cli.git
    cd cli
    make all
    ./prolific
    ```

    You can also install into your `$GOPATH/bin` by running `make build && go install`.
  </Tab>

  <Tab title="Pre-built binaries">
    Download binaries from the [releases page](https://github.com/prolific-oss/cli/releases). Find the release you want, check the "Assets" section, and download the binary for your platform.

    Once downloaded, put the binary in a folder that is referenced in your `$PATH`.
  </Tab>
</Tabs>

### Requirements

* [Go 1.26+](https://go.dev/doc/install) (only needed if building from source)

For more details, see the [installation guide](https://github.com/prolific-oss/cli#installation).

## Configuration

### Authentication

Set the `PROLIFIC_TOKEN` environment variable with your API token:

```shell
export PROLIFIC_TOKEN="<your token>"
```

You can create a Researcher token in your [account settings](https://app.prolific.com/researcher/tokens/).

### Optional settings

You can optionally override the API URL if Prolific have granted you access to a different environment:

```shell
export PROLIFIC_URL="https://api.prolific.com"
```

You can also define defaults in a configuration file at `$HOME/.config/prolific-oss/prolific.yaml`:

```yaml
workspace: <your workspace id>
```

For more details, see the [configuration guide](https://github.com/prolific-oss/cli#configuration) .

## Available commands

```shell
prolific [command]
```

| Command        | Description                                                |
| -------------- | ---------------------------------------------------------- |
| `campaign`     | Provide details about your campaigns                       |
| `completion`   | Generate the autocompletion script for the specified shell |
| `credentials`  | Manage credential pools                                    |
| `filter-sets`  | Manage and view your filter sets                           |
| `help`         | Help about any command                                     |
| `hook`         | Manage and view your hook subscriptions                    |
| `message`      | Send and retrieve messages                                 |
| `participant`  | Manage and view your participant groups                    |
| `project`      | Manage and view your projects in a workspace               |
| `requirements` | List all eligibility requirements available for your study |
| `studies`      | List all of your studies                                   |
| `study`        | Manage and view your studies                               |
| `submission`   | Manage and view your study submissions                     |
| `whoami`       | View details about your account                            |
| `workspace`    | Manage and view your workspaces                            |

### Global flags

| Flag              | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `--config <path>` | Config file (default: `$HOME/.config/prolific-oss/prolific.yaml`) |
| `-h, --help`      | Help for prolific                                                 |
| `-v, --version`   | Version for prolific                                              |

Use `prolific [command] --help` for more information about a specific command.

## Contributing

We welcome contributions. See the [Contributing Guide](https://github.com/prolific-oss/cli/blob/main/CONTRIBUTING.md) on GitHub for details on how to get started.