Pushkin CLI

Skip to section

installation

The Pushkin command-line package is available via Yarn. We highly recommend a global install in order to make working with Pushkin projects as easy as possible:

$ yarn global add pushkin-cli

update

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

$ yarn global upgrade pushkin-cli --latest

Any subcommand that affects a specific project must be run from a folder inside the project you wish to modify.

The CLI has the following subcommands:

config

Syntax: pushkin config [what]

View config file for what , replacing what with site or any of the installed experiments by name. Defaults to all.

install site

Syntax: pushkin install site

Downloads Pushkin site template. It first will prompt for which site template (currently only "default"), then which version. Most often, the latest version will be the best option.

install experiment

Syntax: pushkin install experiment

Downloads an experiment template. First will prompt for which experiment template (see current list here), then prompt for a version to be selected. Most often, the latest version will be the best option.

updateDB

Syntax: pushkin 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

prep

Syntax: pushkin 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.

The command pushkin prep has two optional arguments: --nomigrations and --help.

Run pushkin prep --nomigrations if you do not want to run migrations. If you do this, make sure the database structure has not changed.

Running pushkin start --help will display help for the command.

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 thie following:

  • It compiles and then tarballs the api controllers. These are moved to pushkin/api/tempPackages. This package is then added as a local package to pushkin/api/package.json, which allows them to be called during production.

  • It compiles the 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.

  • It compiles and tarballs web page and moves it to pushkin/front-end/tempPackages. This package is then added as a local package to pushkin/front-end/tempPackages.

Finally, it updates pushkin/front-end/src/experiments.js to list each experiment, along with key information from the experiment’s config file. This will be read by the front end to build the list of experiments to display to potential participants.

Note that before any of this happens, prep actually goes through and deletes all old tempPackages, cleans up the package.jsons and docker-compose-dev.yml and empties experiments.js. Thus, to delete an experiment, all you have to do is delete it’s folder from the experiment folder. (Of course, that won’t get rid of the docker image for the worker, so you’ll need to clean those up by hand periodically.)

start

Syntax: pushkin start [options]

Starts local deploy for debugging purposes. To start only the front end (no databases), see the manual.

The command pushkin start has two optional arguments: --nocache and --help.

Running pushkin start --nocache will rebuild all images from scratch without using the cache. By default, this is false.

Running pushkin start --help will display help for the command.

stop

Syntax: pushkin stop

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

kill

Syntax: pushkin kill

Removes all containers and volumes from local Docker, as well as pushkin-specific images. Sometimes, if you 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.

armageddon

Syntax: pushkin armageddon

Complete reset of the local docker, including containers, volumes, and third-party images. Sometimes, if you 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.

help

Syntax: pushkin help [command]

Provides information on a specific pushkin command, you can 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 specified.