Skip to content

Latest commit

Β 

History

1,201 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

logo

Prolific CLI

A command-line interface for Prolific


GitHub Badge

The CLI for all Prolific interactions β€” built for humans and AI agents.

brew install prolific-oss/tap/prolific see Installation for other options.

CLI application for retrieving data from the Prolific Platform

Usage:
  prolific [command]

Available Commands:
  aitaskbuilder AI Task Builder tools and utilities
  bonus         Create and pay bonuses for study participants
  campaign      Provide details about your campaigns
  collection    Manage and view your collections
  completion    Generate the autocompletion script for the specified shell
  credentials   Manage credential pools
  feedback      View participant feedback for your studies
  filter-sets   Manage and view your filter sets
  filters       List all filters available for your study
  help          Help about any command
  hook          Manage and view your hook subscriptions
  invitation    Manage workspace invitations
  message       Send and retrieve messages
  participant   Manage and view your participant groups
  project       Manage and view your projects in a workspace
  researcher    Manage researcher resources
  studies       List all of your studies
  study         Manage and view your studies
  submission    Manage and view your study submissions
  template      Browse and retrieve study and collection templates
  whoami        View details about your account
  workspace     Manage and view your workspaces

Flags:
      --config string   config file (default is $HOME/.config/prolific-oss/prolific.yaml)
  -h, --help            help for prolific
      --skill string    Optional identifier for the AI skill/workflow invoking this command; folded into the User-Agent header sent with API requests
  -v, --version         version for prolific

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

List view of studies

Detail view of a study

Main features include:

  • Ability to list and filter studies.
  • Ability to list submissions for a given study.
  • Ability to list studies and define which fields to do display in a table format.
  • Ability to render details about a study, and the submissions.
  • Ability to create and update credential pools for studies requiring authentication.
  • Ability to download credentials usage report for a study as CSV.
  • Ability to create a Study via a YAML/JSON configuration file.
  • Ability to publish a study whilst creating it (if you have sufficient funds).
  • Ability to silently create a study, meaning you can script creating many studies in one go.
  • Ability to get your user account details.
  • Ability to list your hook subscriptions.
  • Ability to send and retrieve messages.
  • Ability to list and view your filter sets.
  • Ability to list and view your participant groups.
  • Ability to retrieve participant feedback and aggregate study ratings.

Checkout the wiki for more tips and tricks.

Requirements

If you are wanting to build and develop this, you will need the following items installed. If, however, you just want to run the application I recommend using a binary (See below).

Configuration

You can create studies via a configuration file. See some examples in /docs/examples. It's one study per file.

You can then create a study by calling:

prolific study create -t docs/examples/standard-sample.yaml

You can also define some defaults in the configuration file: $HOME/.config/prolific-oss/prolific.yaml.

Currently you can define the following:

workspace: xxxxxxxxxx

Environment variables

You will need the following environment variables defining:

export PROLIFIC_TOKEN=""

You can create a Researcher token in your account.

You can optionally override the URL for the API too. This will be set as default to the Prolific API URL. You can override this if Prolific have granted you access to a different environment.

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

Installation

You can install this application a few ways:

Installation via Homebrew
brew install prolific-oss/tap/prolific
Installation via Git
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.

Installation via Binaries

You can download the binaries from the release pages. Find the release you want, and check the "Assets" section.

Once downloaded, be sure to put the binary in a folder that is referenced in your $PATH.

Installation via Go Install
go install github.com/prolific-oss/cli/cmd/prolific@latest

Development with Claude Code

When implementing new CLI commands, use the /cli-command-create skill.

Option 1: Natural Language

Simply describe what command you want to create:

Create a new command to publish collections
Add a command that lets users delete studies

Claude will ask follow-up questions to gather the ticket number, API contract, and other details.

Option 2: Slash Command with Arguments

Use the slash command with optional arguments:

/cli-command-create

Or provide arguments directly (ticket, resource, command, command-type):

/cli-command-create DCP-2190 collection publish CREATE
/cli-command-create DCP-2200 study delete ACTION

Argument order: [ticket] [resource] [command] [command-type]

Argument Description Examples
ticket Jira ticket number DCP-2190
resource Resource name collection, study, workspace
command Command name list, get, create, publish
command-type Command type (optional) LIST, VIEW, CREATE, UPDATE, ACTION

If any arguments are omitted, Claude will ask for them interactively.

What the Skill Does

  1. Gathers requirements (API contract, flags, command type)
  2. Presents an implementation plan for approval
  3. Implements model, client, command, UI renderers, mocks, and tests
  4. Verifies with make test and make lint

API Coverage

A full manifest of which Prolific API operations this CLI covers, generated from the test suite that validates the client against the live API spec on every run β€” useful if you're deciding whether to shell out to the CLI or call the API directly from an agent or script.

Operations are grouped as they appear in contract_test/contract_test.go, which validates every entry marked βœ… against the live Prolific OpenAPI spec on every test run.

Workspaces
Operation Method Path Coverage
workspaces_GetWorkspaces GET /api/v1/workspaces/ βœ… GetWorkspaces
workspaces_CreateWorkspace POST /api/v1/workspaces/ βœ… CreateWorkspace
workspaces_GetWorkspace GET /api/v1/workspaces/{workspace_id}/ βž– Not exposed in the CLI
workspaces_UpdateWorkspace PATCH /api/v1/workspaces/{workspace_id}/ βž– Not exposed in the CLI
workspaces_GetWorkspaceBalance GET /api/v1/workspaces/{workspace_id}/balance/ βœ… GetWorkspaceBalance
Projects
Operation Method Path Coverage
projects_GetProjects GET /api/v1/workspaces/{workspace_id}/projects/ βœ… GetProjects
projects_CreateProject POST /api/v1/workspaces/{workspace_id}/projects/ βœ… CreateProject
projects_GetProject GET /api/v1/projects/{project_id}/ βœ… GetProject
projects_UpdateProject PATCH /api/v1/projects/{project_id}/ βž– Not exposed in the CLI
studies_DeleteProjectStudy DELETE /api/v1/projects/{project_id}/studies/{study_id}/ βž– Not exposed in the CLI
Filters
Operation Method Path Coverage
filters_GetFilters GET /api/v1/filters/ βœ… GetFilters
filters_GetEligibleCount POST /api/v1/eligibility-count/ βœ… GetEligibilityCount
Filter Sets
Operation Method Path Coverage
filterSets_GetFilterSets GET /api/v1/filter-sets/ βœ… GetFilterSets
filterSets_CreateFilterSet POST /api/v1/filter-sets/ βœ… CreateFilterSet
filterSets_GetFilterSet GET /api/v1/filter-sets/{id}/ βœ… GetFilterSet
filterSets_DeleteFilterSet DELETE /api/v1/filter-sets/{id}/ βž– Not exposed in the CLI
filterSets_UpdateFilterSet PATCH /api/v1/filter-sets/{id}/ βž– Not exposed in the CLI
filterSets_CloneFilterSet POST /api/v1/filter-sets/{id}/clone/ βž– Not exposed in the CLI
filterSets_LockFilterSet POST /api/v1/filter-sets/{id}/lock/ βž– Not exposed in the CLI
filterSets_UnlockFilterSet POST /api/v1/filter-sets/{id}/unlock/ βž– Not exposed in the CLI
Webhooks
Operation Method Path Coverage
webhooks_GetEventTypes GET /api/v1/hooks/event-types/ βœ… GetHookEventTypes
webhooks_GetSecrets GET /api/v1/hooks/secrets/ βœ… GetHookSecrets
webhooks_CreateSecret POST /api/v1/hooks/secrets/ βœ… CreateHookSecret
webhooks_GetSubscriptions GET /api/v1/hooks/subscriptions/ βœ… GetHooks
webhooks_CreateSubscription POST /api/v1/hooks/subscriptions/ βœ… CreateHookSubscription
webhooks_GetSubscription GET /api/v1/hooks/subscriptions/{subscription_id}/ βž– Not exposed in the CLI
webhooks_ConfirmSubscription POST /api/v1/hooks/subscriptions/{subscription_id}/ βœ… ConfirmHookSubscription
webhooks_DeleteSubscription DELETE /api/v1/hooks/subscriptions/{subscription_id}/ βœ… DeleteHookSubscription
webhooks_UpdateSubscription PATCH /api/v1/hooks/subscriptions/{subscription_id}/ βœ… UpdateHookSubscription
webhooks_GetEvents GET /api/v1/hooks/subscriptions/{subscription_id}/events/ βœ… GetEvents
Surveys
Operation Method Path Coverage
surveys_GetSurveys GET /api/v1/surveys/ βœ… GetSurveys
surveys_CreateSurvey POST /api/v1/surveys/ βœ… CreateSurvey
surveys_GetSurvey GET /api/v1/surveys/{survey_id} βœ… GetSurvey
surveys_DeleteSurvey DELETE /api/v1/surveys/{survey_id} βœ… DeleteSurvey
surveys_GetResponses GET /api/v1/surveys/{survey_id}/responses/ βœ… GetSurveyResponses
surveys_CreateResponse POST /api/v1/surveys/{survey_id}/responses/ βœ… CreateSurveyResponse
surveys_DeleteResponses DELETE /api/v1/surveys/{survey_id}/responses/ βœ… DeleteAllSurveyResponses
surveys_GetSummary GET /api/v1/surveys/{survey_id}/responses/summary/ βœ… GetSurveyResponseSummary
surveys_GetResponse GET /api/v1/surveys/{survey_id}/responses/{response_id} βœ… GetSurveyResponse
surveys_DeleteResponse DELETE /api/v1/surveys/{survey_id}/responses/{response_id} βœ… DeleteSurveyResponse
AI Task Builder β€” Batches
Operation Method Path Coverage
aiTaskBuilder_GetTaskBuilderBatches GET /api/v1/data-collection/batches βœ… GetAITaskBuilderBatches
aiTaskBuilder_CreateTaskBuilderBatch POST /api/v1/data-collection/batches βœ… CreateAITaskBuilderBatch
aiTaskBuilder_GetTaskBuilderBatch GET /api/v1/data-collection/batches/{batch_id} βœ… GetAITaskBuilderBatch
aiTaskBuilder_UpdateTaskBuilderBatch PATCH /api/v1/data-collection/batches/{batch_id} βœ… UpdateAITaskBuilderBatch
aiTaskBuilder_GetTaskBuilderBatchStatus GET /api/v1/data-collection/batches/{batch_id}/status βœ… GetAITaskBuilderBatchStatus
aiTaskBuilder_SetupTaskBuilderBatch POST /api/v1/data-collection/batches/{batch_id}/setup βœ… SetupAITaskBuilderBatch
aiTaskBuilder_GetTaskBuilderBatchTaskResponses GET /api/v1/data-collection/batches/{batch_id}/responses βœ… GetAITaskBuilderResponses
aiTaskBuilder_GetTaskBuilderBatchReport GET /api/v1/data-collection/batches/{batch_id}/report/ βž– Not exposed in the CLI
aiTaskBuilder_DuplicateTaskBuilderBatch POST /api/v1/data-collection/batches/{batch_id}/duplicate βž– Not exposed in the CLI
aiTaskBuilder_SyncTaskBuilderBatch POST /api/v1/data-collection/batches/{batch_id}/sync βœ… SyncAITaskBuilderBatch
aiTaskBuilder_GetBatchSyncStatus GET /api/v1/data-collection/batches/{batch_id}/syncs/{sync_id} βœ… GetAITaskBuilderBatchSyncStatus
aiTaskBuilder_RequestBatchExport POST /api/v1/data-collection/batches/{batch_id}/export βœ… InitiateBatchExport
aiTaskBuilder_GetBatchExportStatus GET /api/v1/data-collection/batches/{batch_id}/export/{export_id} βœ… GetBatchExportStatus
AI Task Builder β€” Datasets
Operation Method Path Coverage
aiTaskBuilder_CreateTaskBuilderDataset POST /api/v1/data-collection/datasets βœ… CreateAITaskBuilderDataset
aiTaskBuilder_UpdateTaskBuilderDataset PATCH /api/v1/data-collection/datasets/{dataset_id} βž– Not exposed in the CLI
aiTaskBuilder_AppendDatasetDatapoints POST /api/v1/data-collection/datasets/{dataset_id}/datapoints βž– Not exposed in the CLI
aiTaskBuilder_getDatasetUploadUrl GET /api/v1/data-collection/datasets/{dataset_id}/upload-url/{filename} βœ… GetAITaskBuilderDatasetUploadURL
aiTaskBuilder_GetTaskBuilderDataset GET /api/v1/data-collection/datasets/{dataset_id} βœ… GetAITaskBuilderDataset
aiTaskBuilder_GetTaskBuilderDatasetStatus GET /api/v1/data-collection/datasets/{dataset_id}/status βœ… GetAITaskBuilderDatasetStatus
aiTaskBuilder_GetDatasetImportStatus GET /api/v1/data-collection/datasets/{dataset_id}/imports/{import_id} βœ… GetAITaskBuilderDatasetImportStatus
aiTaskBuilder_GetSchemaMigrationStatus GET /api/v1/data-collection/datasets/{dataset_id}/schema-migrations/{job_id} βž– Not exposed in the CLI
AI Task Builder β€” Instructions
Operation Method Path Coverage
aiTaskBuilder_GetTaskBuilderInstructions GET /api/v1/data-collection/batches/{batch_id}/instructions βž– Not exposed in the CLI
aiTaskBuilder_CreateTaskBuilderInstructions POST /api/v1/data-collection/batches/{batch_id}/instructions βœ… CreateAITaskBuilderInstructions
aiTaskBuilder_UpdateTaskBuilderInstructions PUT /api/v1/data-collection/batches/{batch_id}/instructions βž– Not exposed in the CLI
AI Task Builder β€” Collections
Operation Method Path Coverage
aiTaskBuilder_ListCollections GET /api/v1/data-collection/collections βœ… GetCollections
aiTaskBuilder_CreateCollection POST /api/v1/data-collection/collections βœ… CreateAITaskBuilderCollection
aiTaskBuilder_GetCollection GET /api/v1/data-collection/collections/{collection_id} βœ… GetCollection
aiTaskBuilder_UpdateCollection PUT /api/v1/data-collection/collections/{collection_id} βœ… UpdateCollection
aiTaskBuilder_GetCollectionResponses GET /api/v1/data-collection/collections/{collection_id}/responses βž– Not exposed in the CLI
aiTaskBuilder_RequestCollectionExport POST /api/v1/data-collection/collections/{collection_id}/export βœ… InitiateCollectionExport
aiTaskBuilder_GetCollectionExportStatus GET /api/v1/data-collection/collections/{collection_id}/export/{export_id} βœ… GetCollectionExportStatus
Invitations
Operation Method Path Coverage
invitations_CreateInvitation POST /api/v1/invitations/ βœ… CreateInvitation
Messages
Operation Method Path Coverage
messages_GetMessages GET /api/v1/messages/ βœ… GetMessages
messages_SendMessage POST /api/v1/messages/ βœ… SendMessage
messages_BulkMessageParticipants POST /api/v1/messages/bulk/ βœ… BulkSendMessage
messages_SendMessageToParticipantGroup POST /api/v1/messages/participant-group/ βœ… SendGroupMessage
messages_GetUnreadMessages GET /api/v1/messages/unread/ βœ… GetUnreadMessages
messages_GetConversations GET /api/v1/conversations/ βž– Not exposed in the CLI
messages_GetConversationMessages GET /api/v1/conversations/{conversation_id}/messages/ βž– Not exposed in the CLI
Studies
Operation Method Path Coverage
studies_GetStudies GET /api/v1/studies/ βœ… GetStudies
studies_CreateStudy POST /api/v1/studies/ βœ… CreateStudy
studies_GetProjectStudies GET /api/v1/projects/{project_id}/studies/ βœ… GetStudies
studies_DeleteProjectStudy DELETE /api/v1/projects/{project_id}/studies/{study_id}/ βž– Not exposed in the CLI
studies_GetStudy GET /api/v1/studies/{id}/ βœ… GetStudy
studies_DeleteStudy DELETE /api/v1/studies/{id}/ βž– Not exposed in the CLI
studies_UpdateStudy PATCH /api/v1/studies/{id}/ βœ… UpdateStudy
studies_PublishStudy POST /api/v1/studies/{id}/transition/ βœ… TransitionStudy
studies_CreateTestStudy POST /api/v1/studies/{id}/test-study βœ… TestStudy
studies_GetStudyAccessDetailsProgress GET /api/v1/studies/{id}/access-details-progress/ βž– Not exposed in the CLI
studies_GetStudyCost GET /api/v1/studies/{id}/cost/ βž– Not exposed in the CLI
studies_GetStudySubmissions GET /api/v1/studies/{id}/submissions/ βœ… GetSubmissions
studies_CountStudySubmissionsByStatus GET /api/v1/studies/{id}/submissions/counts/ βœ… GetStudySubmissionCounts
studies_DownloadStudyCredentialReport GET /api/v1/studies/{id}/credentials/report/ βœ… GetStudyCredentialsUsageReportCSV
studies_ExportStudy GET /api/v1/studies/{id}/export/ βž– Not exposed in the CLI
studies_ExportDemographicData POST /api/v1/studies/{id}/demographic-export/ βœ… ExportDemographics
studies_GetDemographicExportHistory GET /api/v1/studies/{id}/demographic-export-history/ βž– Not exposed in the CLI
studies_DuplicateStudy POST /api/v1/studies/{id}/clone/ βœ… DuplicateStudy
studies_CalculateStudyCost POST /api/v1/study-cost-calculator/ βž– Not exposed in the CLI
Credentials
Operation Method Path Coverage
credentials_ListCredentialPools GET /api/v1/credentials/ βœ… ListCredentialPools
credentials_CreateCredentialPool POST /api/v1/credentials/ βœ… CreateCredentialPool
credentials_UpdateCredentialPool PATCH /api/v1/credentials/{credential_pool_id}/ βœ… UpdateCredentialPool
Reward Recommendations
Operation Method Path Coverage
rewardRecommendations_CalculateRewardRecommendations GET /api/v1/reward-recommendations/ βœ… GetRewardRecommendations
Well-known endpoints
Operation Method Path Coverage
wellKnownEndpoints_getStudyJwks GET /.well-known/study/jwks.json βž– Not exposed in the CLI
Submissions
Operation Method Path Coverage
submissions_GetSubmissions GET /api/v1/submissions/ βž– Not exposed in the CLI
submissions_GetSubmission GET /api/v1/submissions/{id}/ βž– Not exposed in the CLI
submissions_TransitionSubmission POST /api/v1/submissions/{id}/transition/ βœ… TransitionSubmission
submissions_RequestSubmissionReturn POST /api/v1/submissions/{id}/request-return/ βœ… RequestSubmissionReturn
submissionFeedbackUpload_GetSubmissionFeedbackUploadUrl GET /api/v1/submissions/signals/upload-url/{filename} βž– Not exposed in the CLI
submissions_BulkApproveSubmissions POST /api/v1/submissions/bulk-approve/ βœ… BulkApproveSubmissions
Bonuses
Operation Method Path Coverage
bonuses_CreateBonusPayments POST /api/v1/submissions/bonus-payments/ βœ… CreateBonusPayments
bonuses_PayBonusPayments POST /api/v1/bulk-bonus-payments/{id}/pay/ βœ… PayBonusPayments
Users
Operation Method Path Coverage
users_GetUser GET /api/v1/users/me/ βœ… GetMe
users_CreateTestParticipantForResearcher POST /api/v1/researchers/participants/ βœ… CreateTestParticipant
Participant Groups
Operation Method Path Coverage
participantGroups_GetParticipantGroups GET /api/v1/participant-groups/ ⚠️ Covered, not spec-validated β€” test harness limitation
participantGroups_CreateParticipantGroup POST /api/v1/participant-groups/ βœ… CreateParticipantGroup
participantGroups_GetParticipantGroup GET /api/v1/participant-groups/{id}/ βž– Not exposed in the CLI
participantGroups_DeleteParticipantGroup DELETE /api/v1/participant-groups/{id}/ βž– Not exposed in the CLI
participantGroups_UpdateParticipantGroup PATCH /api/v1/participant-groups/{id}/ βž– Not exposed in the CLI
participantGroups_GetParticipantGroupParticipants GET /api/v1/participant-groups/{id}/participants/ βœ… GetParticipantGroup
participantGroups_AddToParticipantGroup POST /api/v1/participant-groups/{id}/participants/ βœ… AddParticipantGroupMembers
participantGroups_RemoveFromParticipantGroup DELETE /api/v1/participant-groups/{id}/participants/ βœ… RemoveParticipantGroupMembers

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

Release Process

Releases are managed via GitHub Releases with changelog generation powered by git-cliff.

1. Generate changelog

make changelog VERSION=0.0.60

This generates grouped release notes from conventional commits, merges any hand-written notes from the ## next section of CHANGELOG.md, and updates the changelog file.

2. Create a release PR

Create a PR with the updated CHANGELOG.md and apply the release label.

One CI gate will validate the PR:

  • Changelog gate β€” confirms CHANGELOG.md is modified when the release label is present.

Steps 1–2 can also happen automatically. .github/workflows/release-cadence-check.yml runs weekly (and on manual workflow_dispatch) checking for unreleased user-facing commits on main; if it finds any, it runs make changelog and opens a release PR itself, defaulting to a PATCH version bump. It never merges, tags, or releases anything β€” step 3 below still requires a human to review and merge, exactly as if the PR had been opened by hand. If the auto-computed PATCH bump is wrong for a given batch of changes (i.e. it includes a breaking change), edit the version heading in the PR's CHANGELOG.md diff to the next MINOR version before merging.

Not the right time to release (e.g. other work is still landing and you'd rather batch it in)? Closing an auto-opened PR without merging is a normal way to defer β€” it isn't permanent, and the next scheduled run will propose a fresh PR if unreleased commits still remain.

3. Merge to trigger the release

Merging the PR to main triggers .github/workflows/create-release.yml on that push. The workflow only performs a release when the merged PR has the release label (it checks linked PRs for that label); other pushes to main do not create tags or releases.

When a release runs, it automatically:

  1. Extracts the version from the top-most ## x.y.z section in CHANGELOG.md
  2. Creates and pushes a vx.y.z git tag
  3. Creates a GitHub Release titled vx.y.z (always use the v prefix for tags and release names, e.g. v1.0.1, not 1.0.1) with the matching changelog section as release notes
  4. Builds binaries for multiple platforms (darwin, linux, windows, freebsd) and uploads them to the release

Users can then download binaries from the release page or use go install.

About

πŸ”¬ A CLI for managing and automating workflows on the Prolific platform

Resources

Contributing

Stars

13 stars

Watchers

5 watching

Forks

Releases

Contributors

Languages