pushkin-cli

Installation

We recommend installing the Pushkin command-line interface globally for ease of setting up your Pushkin site:

 yarn global add pushkin-cli

Updating pushkin-cli

To update Pushkin CLI to the most recently released version, run:

 yarn global upgrade pushkin-cli --latest

Commands

config

View the config file for your site or any of the installed experiments.

Syntax

pushkin config <what>

Arguments

• what: string

  Can be site or the name of any of the installed experiments. If omitted, all config files are shown.

install site

This command uses a template to set up the file structure of your site in the current working directory. You will be prompted to select which template and version you want. Typically, the latest version will be the best option. You also have options to install a template from an arbitrary npm package(1) or from a local path. The latter option is particularly useful for developing your own site templates and for using unreleased development versions of templates.

1. Of course, this will only work if the package is properly set up to function as a Pushkin site template.

How can I work on multiple Pushkin sites simultaneously?

When running Pushkin on your local system, you can only work on a single Pushkin site at a time. For most users, this shouldn't present a problem, since additional experiments can always be added to a site; however, if you do need to work on multiple sites simultaneously, using GitHub Codespaces will allow you to keep your sites in separate virtual environments.

Syntax:

pushkin install site <options>

or

pushkin i site <options>

Options:

• verbose: -v or --verbose shows additional console output during the installation process which may be helpful for debugging.

• help: -h or --help displays the command's help information.

Details:

In general, it's a best practice to install your Pushkin site in a new directory. The CLI will ask you to confirm the installation if there are already contents in your working directory. In some cases you may wish to install a site into a directory that already has some contents, e.g. if the directory has already been initialized as a git repository and has a /.git directory.

install site generally works by initializing your site directory as a private npm package so Pushkin templates can be added as dependencies. Template contents then get unzipped into your site directory and are further manipulated by the CLI.

install site also sets up your Pushkin site’s test transactions database, a test version of the eventual production transactions database. The command reviews the presence of configuration files pushkin/docker-compose.dev.yml and pushkin.yaml. These configurations detail the database setup, including parameters such as ports and passwords. Should necessary configurations for the test transaction database be absent, the command establishes them automatically.

The transactions database, like all Pushkin databases, uses PostgreSQL and Knex migrations. Migration files serve as blueprints for database tables. If migration files for the transactions database are missing, the command automatically establishes a standard structure for it.

install site also does some initial dependency installation and building for the /pushkin/front-end and /pushkin/api components.

install experiment

This command helps users set up a new experiment using a Pushkin experiment template. You will be prompted to select which template and version you want. Typically, the latest version will be the best option. You also have options to install a template from an arbitrary npm package(1) or from a local path. The latter option is particularly useful for developing your own experiment templates and for using unreleased development versions of templates.

1. Of course, this will only work if the package is properly set up to function as a Pushkin experiment template.

Syntax:

pushkin install experiment <options>

or

pushkin i exp <options>

Options:

• verbose: -v or --verbose shows additional console output during the installation process which may be helpful for debugging.

• help: -h or --help displays the command's help information.

Details:

If you select the basic template, this command will give you the option to import an existing jsPsych experiment (note that the latest basic template and thus this feature only support jsPsych 7+). This feature assumes a workflow where you first implement the basics of your experiment design as a standalone jsPsych experiment, which is a bit faster to test, before turning it into a Pushkin experiment. This feature is covered in detail in the documentation for the basic experiment template.

install experiment generally works by adding the experiment template of your choosing as a dependency to your site. Template contents then get unzipped into the experiment's dedicated directory and are further manipulated by the CLI.

The command also integrates a new experiment into the Pushkin framework. It performs key tasks such as updating template file names and contents to reflect the new experiment's name, setting up database migrations, initializing essential directories for the experiment's API, web page, and worker components, and ensuring the experiment is correctly configured in the Docker environment. The API and web page components are then locally published using yalc.

remove experiment

This command allows users to remove an experiment from their site and offers three removal modes:

1. delete: Deleting an experiment permanently removes all of its files, data, and associated Docker components. This command should only be used if you want the experiment completely gone, as it is irreversible. Note that this mode currently runs kill, and will consequently delete all experiments' data from your local database, not just the experiment(s) you deleted. Future development may address this limitation.
2. archive: Archiving an experiment removes it from your site's front end, so it is no longer accessible to participants. However, all of the experiment's files remain in place and the site's back end and data will not be affected.
3. pause-data: Pausing data collection means that the front end of the experiment stays accessible, but no data from subsequent runs of that experiment will be saved to the Pushkin database. When data collection is paused, an additional trial is added to the beginning of the experiment informing potential participants that no data will be collected.

The archive and pause-data modes have complementary modes unarchive and unpause-data which respectively restore an archived experiment to the front end and resume data collection. The delete mode has no such complement, since it is permanent.

Note

You must run prep after remove experiment for the changes to your site to take effect.

Syntax:

pushkin remove experiment <options>

or

pushkin rm exp <options>

Options:

• experiments: -e or --experiments allows you to specify which experiment(s) to delete, archive, or unarchive. Provide the experiments' short names (i.e. the name of the folder in the /experiments directory) separated by spaces after the -e flag (e.g. pushkin rm exp -e exp1 exp2 exp3). If the --experiments option is omitted, the CLI will interactively prompt you to select the experiments you want.

• mode: -m or --mode allows you to specify the delete, archive, unarchive, pause-data, or unpause-data mode (e.g. pushkin rm exp -m delete). If the --mode option is omitted, the CLI will interactively prompt you to select which mode you want.

• force: -f or --force applies only to the delete mode and allows you to suppress the deletion confirmation prompt.

• verbose: -v or --verbose shows additional console output during the removal process which may be helpful for debugging.

• help: -h or --help displays the command's help information.

Details:

All that results from calling remove experiment in the archive or pause-data mode (as well as their opposite modes) is that the experiment's config.yaml file will be updated with respect to the boolean property archived or dataPaused. You can change this property manually if you wish, but using pushkin rm exp -m archive or pushkin rm exp -m pause-data offers a convenient way to quickly change this property for multiple experiments.

updateDB

Runs migrations and seeds for experiments to update the database. This is set up to ensure experiments using the same database (as defined in pushkin.yaml) are migrated at the same time to avoid errors with the knex_migrations table. This is automatically run as part of pushkin prep.

Syntax:

pushkin updateDB

prep

Run inside a Pushkin project to prepare Pushkin to be run for local testing. Packages generated by yarn inside each experiment’s web page and api controllers directories are moved to the core Pushkin code, installed there, and linked to the core code. Previous modules are uninstalled and removed.

Syntax:

pushkin prep <options>

Options:

• no-migrations: --no-migrations will run prep without database migrations. If you do this, make sure the database structure has not changed since you ran prep previously (with migrations).

• verbose: -v or --verbose shows additional console output which may be helpful for debugging.

• help: -h or --help displays the command's help information.

Details:

The code for prep is a bit convoluted (sorry). It loops through each experiment in the experiments folder (as defined by pushkin.yaml). For each experiment, it does the following:

• builds and locally publishes the experiment's api controllers and web page components. These are then added to the site's core API and front-end packages, respectively.
• compiles the experiment's worker and then builds a Docker image for it. It is then added to docker-compose.dev.yml so that docker knows to include it when the website is built.
• updates pushkin/front-end/src/experiments.js to list the experiment, along with key information from its config file. This will be read by the front end to build the list of experiments to display to potential participants.

Additionally, prep builds the other docker images for remaining components of the Pushkin site, including the main database, the transactions database, the API, and the front end.

start

Starts the local deploy of your Pushkin site for debugging purposes.

Syntax:

pushkin start <options>

Options:

• no-cache: --no-cache will rebuild all Docker images from scratch without using the cache. By default, this is false.

• verbose: -v or --verbose shows additional console output which may be helpful for debugging.

• help: -h or --help displays the command's help information.

stop

Stops the local deploy. This will not remove the local Docker images. To do that, see pushkin kill and pushkin armageddon.

Syntax:

pushkin stop

kill

Removes all containers and volumes from local Docker, as well as pushkin-specific images. Sometimes, if you're having issues developing or seeing updates to your Pushkin project, it may be helpful to run this command to ensure docker isn't holding any problematic code or issues in containers.

Syntax:

pushkin kill

armageddon

Performs a complete reset of local Docker, including containers, volumes, and third-party images. Sometimes, if you're having issues developing or seeing updates to your Pushkin project, it may be helpful to run this command to ensure docker isn't holding any problematic code or issues in containers/images. This may generate some error messages, which you can safely ignore.

Syntax:

pushkin armageddon

help

Provides help information for pushkin commands.

Syntax:

pushkin help <command>

Arguments:

• command: string

  Add the command after help (e.g. pushkin help prep to learn about the prep command and its options). Defaults to a list of all commands and general information about each if no command is specified.