README.md

PubSweet CLI

command-line tools for managing PubSweet apps

Contents

• Introduction
  • PubSweet overview
    • PubSweet modules
• Getting started with PubSweet CLI
  • Getting PubSweet CLI
    • Prerequisites
    • Installation
    • Installation on Windows
  • Using PubSweet CLI
    • Displaying the commands (pubsweet or pubsweet help)
    • Generating an app (pubsweet new)
    • Running your app (pubsweet run)
    • Setting up the database (pubsweet setupdb)
    • Adding a user to the database (pubsweet adduser)
• Contributing

Introduction

PubSweet overview

PubSweet allows you to build state-of-the-art publishing platforms.

It's a modular and flexible framework consisting of a server and client that work together, components that can modify or extend the functionality of the server and/or client, and a command-line tool that helps manage PubSweet apps.

PubSweet modules

repository	description
pubsweet/pubsweet-server	an extensible server API that runs on the server
pubsweet/pubsweet-client	an extensible client app that runs in the browser
pubsweet/pubsweet-components	pluggable extensions for server and/or client
pubsweet/pubsweet-cli	a suite of command-line tools for building and managing your platform

Getting started with PubSweet CLI

Getting PubSweet CLI

Prerequisites

• Node.js v7.6+
• npm v3+ or yarn v0.21+

Installation

The PubSweet command-line tools can be installed from npm or yarn:

npm install --global pubsweet

or

yarn global add pubsweet

Installation on Windows

• Install Ubuntu on Windows: Windows Store
• Launch the Bash on Ubuntu on Windows from the Start menu
• Install nvm: nvm install script

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.2/install.sh | bash

• Restart your terminal/bash
• nvm install 7.7 (this version of Node.js is the latest to have precompiled leveldown packages)
• npm install -g pubsweet

Using PubSweet CLI

Displaying the commands (pubsweet or pubsweet help)

Outputs:

Usage: pubsweet [options] [command]


Commands:

  new         create and set up a new pubsweet app
  run         start a pubsweet app
  setupdb     generate a database for a pubsweet app
  add         add one or more components to a pubsweet app
  remove      remove one or more components from a pubsweet app
  adduser     add a user to the database for a pubsweet app
  help [cmd]  display help for [cmd]

Options:

  -h, --help     output usage information
  -V, --version  output the version number

For any command, you can see detailed usage help by running pubsweet help cmd, e.g.:

pubsweet help new
pubsweet help run
[...etc]

Generating an app (pubsweet new)

The new subcommand generates a template PubSweet app for you to work from. This includes everything needed to run your publishing platform: dependencies, database setup, boilerplate code and configuration, and a set of initial components.

To generate an app, just provide the name:

pubsweet new myappname

pubsweet will create a subdirectory with the name you supplied, and start generating the app inside. It'll ask you a series of questions to customise your app. If you prefer to provide the answers in the initial command, you can do that instead:

pubsweet new myappname \
  --username someuser \
  --email some@email.com \
  --password correct-horse-battery-staple \
  --collection Articles

Running your app (pubsweet run)

The run subcommand starts your app. It takes care of transpilation, module bundling and process management.

To start your app:

either use the run command from the app directory:

cd myappname
pubsweet run

or provide the app path to the run command:

pubsweet run path/to/myapp

Adding and removing components (pubsweet add)

Components add pages, actions, and behaviors to pubsweet. There are many we've bundled by default, and you can create your own. To read more about components, read the documentation.

pubsweet add users-manager

Find all available components by typing:

pubsweet components

To remove a component, simply type remove with one or more components:

pubsweet remove users-manager,teams-manager

Setting up the database (pubsweet setupdb)

The setupdb subcommand creates the database for your app. It is usually used when you've cloned the source code of an existing app, or when you want to start over with a fresh database.

To generate a database for an app that doesn't have one yet:

pubsweet setupdb ./path/to/app/dir

By default this will generate a production database only. To generate a dev database, run the command with --dev:

pubsweet setupdb --dev ./path/to/app/dir

If your app already has a database, pubsweet setupdb will not overwrite it by default. You can force it to delete an existing database and overwrite it with a new one using --clobber:

$ pubsweet setupdb ./path/to/app/dir
info: Generating PubSweet app database at path api/db/production
error: Database appears to already exist
error: If you want to overwrite the database, use --clobber
$ pubsweet setupdb --clobber ./path/to/app/dir
info: Generating PubSweet app database at path api/db/production
info: Database appears to already exist
info: Overwriting existing database due to --clobber flag
info: setting up the database
info: building prompt
question:><Admin username><
[...etc]

As with pubsweet new, you can skip any or all of the interactive prompts by providing the user details with command-line flags:

pubsweet setupdb ./path/to/app/dir \
  --username someuser \
  --email some@email.com \
  --password correct-horse-battery-staple \
  --collection Articles

Adding a user to the database (pubsweet adduser)

You can add a user to an existing database:

pubsweet adduser ./path/to/app/dir

You can optionally make that user an admin:

pubsweet adduser --admin ./path/to/app/dir

As with pubsweet new and pubsweet setupdb, you can skip any or all of the interactive prompts by providing the user details with command-line flags:

pubsweet adduser ./path/to/app/dir \
  --username someuser \
  --email some@email.com \
  --password correct-horse-battery-staple

Contributing

Please read our CONTRIBUTING guide.

Credits

pubsweet-cli is part of the PubSweet ecosystem.

PubSweet is part of the Collaborative Knowledge Foundation family.

NOTE: for dev, necessary to run npm link in current dir and npm link pubsweet in @pubsweet-starter dir