======================
Using the command line
======================
In this section we'll learn how we can use the command line to interact with
our project in a PyBossa server, using the command line tool: **pbs**.
.. _pbs:
pbs
===
**pbs** is a very simple command line interface to a PyBossa server. It allows
you to create projects, add tasks (from a CSV or JSON file) with a nice
progress bar, delete them and update the project templates
(tutorial, task_presenter, and descriptions) all from the command line.
Installation
============
pbs is available in Pypi, so you can install the software with pip:
.. code-block:: bash
pip install pybossa-pbs
.. note::
We recommend to use virtual environments to install new Python libraries
and packages, so please, before installing the pbs command line tool
consider using a virtual environment.
If you have all the dependencies, the package will be installed and you will be
able to use it from the command line. The command is: **pbs**.
Configuring pbs
===============
By default, pbs does not need a config file, however you will have to specify
for every command the server and your API key in order to add tasks, create
a project, etc, etc. For specifying the server and API key that you want to
use, all you have to do is pass it as an argument:
.. code-block:: bash
pbs --server http://server.com --api-key yourkey subcommand
If you work with two or more servers, then, remembering all the keys, and
server urls could be problematic, as well as you will be leaving a trace in
your BASH history file. For this reason, pbs has a configuration file where you
can add all the servers that you are working with.
To create the config file, all you have to do is creating a **.pybossa.cfg**
file in your home folder:
.. code-block:: bash
cd ~
vim .pybossa.cfg
The file should have the following structure:
.. code-block:: python
[default]
server: http://theserver.com
apikey: yourkey
If you are working with more servers, add another section below it. For
example:
.. code-block:: python
[default]
server: http://theserver.com
apikey: yourkey
[crowdcrafting]
server: http://crowdcrafting.org
apikey: yourkeyincrowdcrafting
By default pbs will use the credentials of the default section, so you don't
have to type anything to use those values. However, if you want to do actions
in the other server, all you have to do is the following:
.. code-block:: bash
pbs --credentials crowdcrafting --help
That command will use the values of the crowdcrafting section.
Creating a project
==================
Creating a project is very simple. All you have to do is create a file named
**project.json** with the following fields:
.. code-block:: js
{
"name": "Flickr Person Finder",
"short_name": "flickrperson",
"description": "Image pattern recognition",
"question": "Do you see a real human face in this photo?"
}
If you use the name **project.json** you will not have to pass the file name
via an argument, as it's the named used by default. Once you have the file
created, run the following command:
.. code-block:: bash
pbs create_project
That command should create the project. If you want to see all the available
options, please check the **--help** command:
.. code-block:: bash
pbs create_project --help
Adding tasks to a project
=========================
Adding tasks is very simple. You can have your tasks in two formats:
* JSON
* CSV
Therefore, adding tasks to your project is as simple as this command:
.. code-block:: bash
pbs add_tasks --tasks-file tasks_file.json
If you want to see all the available
options, please check the **--help** command:
.. note::
By default PyBossa servers use a rate limit for avoiding abuse of the
API. For this reason, you can only do usually 300 requests per every 15
minutes. If you are going to add more than 300 tasks, pbs will detect it and
warn you, auto-enabling the throttling for you to respect the limits.
Please, see :ref:`rate-limiting` for more details.
.. code-block:: bash
pbs add_tasks --help
Updating project templates
==========================
Now that you have added tasks, you can work in your templates. All you have to
do to add/update the templates to your project is running the following
command:
.. code-block:: bash
pbs update_project
That command needs to have in the same folder where you are running it, the
following files:
* template.html
* results.html
* long_description.md
* tutorial.html
If you want to use another template, you can via arguments:
.. code-block:: bash
pbs update_project --template /tmp/template.html
If you want to see all the available
options, please check the **--help** command:
.. code-block:: bash
pbs update_project --help
Deleting tasks from a project
=============================
If you need it, you can delete all the tasks from your project, or only one
using its task.id. For deleting all the tasks, all you've to do is run the
following command:
.. code-block:: bash
pbs delete_tasks
This command will confirm that you want to delete all the tasks and associated
task_runs.
If you want to see all the available
options, please check the **--help** command:
.. code-block:: bash
pbs delete_tasks --help
.. note::
**Only tasks that are not associated with a result will be deleted.**