Pushkin CLI
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
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:
Syntax: pushkin config [what]
View config file for what , replacing what with site or any of the installed experiments by name. Defaults to all.
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.
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.
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
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.
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 topushkin/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.ymlso that docker knows to include it when the website is built.It compiles and tarballs
web pageand moves it topushkin/front-end/tempPackages. This package is then added as a local package topushkin/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.)
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.
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.
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.
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.
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.