CLI

The psycloud command-line interface drives the whole lifecycle from a terminal — authoring locally, validating and compiling bundles, importing experiments, and (with a hosted backend) deploying and recruiting. It's the backbone of reproducible, CI-friendly workflows.

Generated reference

This page covers the commands and workflows you'll use most. The exhaustive, always-current option list is generated from psycloud --help; run psycloud <command> --help for the full flags of any command.

Commands at a glance

Command	Purpose	Needs backend?
`psycloud init <name>`	Scaffold a new experiment	No
`psycloud serve <script>`	Dev server with live reload	No
`psycloud run <script>`	Run a bundle locally (or create a cloud run)	Local: no
`psycloud build <script>`	Build a standalone HTML file	No
`psycloud validate <path>`	Validate a Project Bundle	No
`psycloud inspect <path>`	Show a bundle's design/screens/bindings	No
`psycloud compile <path>`	Compile Project Bundle → Study Bundle	No
`psycloud import <source>`	Import jsPsych / PsychoJS / a bundle	No
`psycloud export-code <source>`	Generate Python/R/TS code from a study	No
`psycloud workbench …`	Preflight, plots, previews (CI artifacts)	No
`psycloud deploy <path>`	Deploy a bundle to the cloud (a Release)	Yes
`psycloud run create / activate`	Create and activate a participant run	Yes
`psycloud recruit mturk …`	MTurk recruitment	Yes
`psycloud cloud …`	Projects, studies, connectors, exports	Yes

Author locally

Write an experiment in any supported surface, then iterate with live reload, run it once, or build a standalone file:

psycloud serve experiment.coffee -p 3333 -o   # live-reload dev server, opens browser
psycloud run   experiment.coffee              # run a single execution
psycloud build experiment.coffee -o index.html

Validate and compile a bundle

This is the core local workflow for a study authored with the Python or R SDK (which emit a Project Bundle directory):

psycloud validate ./my-experiment --strict      # structure check, no compile
psycloud inspect  ./my-experiment --section design
psycloud compile  ./my-experiment --mode publish --out ./dist/bundle.json

For CI, the workbench commands emit machine-readable reports and visualizations:

psycloud workbench preflight ./bundle --out report.json --html report.html --strict
psycloud workbench plot flow  ./bundle -o flow.html
psycloud workbench plot trials ./bundle -o trials.txt --format ascii

Import and export

# Import an existing experiment (auto-detects jsPsych / PsychoJS / bundle)
psycloud import ./experiment.html --dry-run           # validate only
psycloud import ./experiment.html --out ./imported
 
# Generate idiomatic SDK code from a study or bundle
psycloud export-code ./study.json --lang python -o design.py
psycloud export-code ./study.json --lang r      -o design.R

See Interoperability for the round-trip story.

Cloud: deploy, run, recruit, export

Requires a hosted backend and authentication

The commands below talk to the PsyCloud control plane. Authenticate first with psycloud auth login --api <url>. Everything above this section works fully offline.

A typical end-to-end cloud session, without ever opening Studio:

psycloud auth login --api https://your-psycloud-host
 
# Create a project and study
psycloud cloud projects create --workspace <workspaceId> --name "My Project"
psycloud cloud studies  create --project   <projectId>   --title "Circle RT"
 
# Deploy a bundle as an immutable Release, then create and activate a Run
psycloud deploy --cloud --study <studyId> ./dist/bundle-dir
psycloud run create --release <bundleHash> --name "Pilot"
psycloud run activate --run <runId>
 
# Recruit (MTurk sandbox shown) and export results
psycloud recruit mturk create --run <runId> --assignments 3 --environment sandbox
psycloud recruit mturk publish --run <runId>
psycloud cloud exports run-csv --run <runId> --out results.csv